More interfaces now render while the response is still being generated. The UI begins in one state, then updates as more data comes in. You see this in chat apps, logs, transcription tools, and other real-time systems.

The tricky part is that the interface is not in a fixed state; it keeps changing as new content comes in. It grows where lines become longer and new blocks appear. Something that was just below the screen can suddenly move, and the user’s scroll position becomes harder to manage. Parts of the UI might even be incomplete while the user is already interacting with it.

In this article, we’ll take a simple interface and make it handle this properly. We’ll look at how to keep things stable, manage scrolling, and render partial content without breaking the reading experience.

What Does A Streaming UI Actually Look Like?

I’ve built three demos that stream content in different ways: a chat bubble, a log feed, and a transcription view. They look different on the surface, but they all run into the same three problems.

The first is scroll. When content is streaming in, most interfaces keep the viewport pinned to the bottom. That works if you are just watching, but the moment you scroll up to read something, the page snaps back down. You did not ask for that. The interface decided for you, and now you’re fighting it instead of reading.

The second is layout shift. Streaming content means containers are constantly growing, and as they do, everything below shifts downward. A button you were about to click is no longer where it was. A line you were reading has moved. The page is not broken; it is just that nothing stays still long enough to interact with comfortably.

The third is render frequency. Browsers paint the screen around 60 times per second, but streams can arrive much faster than that. This means the DOM, which is the browser’s internal representation of everything on the page, ends up being updated for frames the user will never actually see. Each update still costs something, and that cost adds up quietly until performance starts to slip.

As you go through each demo, pay attention to where things start feeling off. That small moment of friction when the interface starts getting in your way. This is exactly what we are here to fix.

Example 1: Streaming AI Chat Responses

This is the most familiar case. You click Stream, and the message starts growing token by token, just like a typical AI chat interface.

Here’s what I want you to try:

• Click the Stream button.
• Try scrolling upwards while the message is streaming.
• Increase the speed (to something like 10ms).

You will notice something subtle but important: the UI keeps trying to pull you back down. Basically, it is making a decision for you about where your attention should be.

That’s one example. Let’s look at another.

Example 2: Live Processing In A Log Viewer

This example looks different on the surface, but the problem is actually very similar to the first example. Rather than a message that gets longer over time, new lines are appended continuously, like a terminal or a log stream.

The interesting part here is the tail toggle. It makes the trade-off between interaction and stable interfaces very clear:

Again, here is what I want you to try:

• Click the Start button.
• Allow the logs to stream past the container’s height.
• Scroll up to the beginning.
• Stop the stream and disable the “tail” option.

Notice that, when tail is enabled, the UI follows the new content. But you’re unable to scroll up and stay in place. Instead, you need to stop the stream or enable “tail” to explore the content.

Example 3: Dashboard Displaying Real-Time Metrics

In this case, the UI updates in place:

• Numbers change,
• Charts shift,
• Values refresh continuously.

There is no scroll tension this time, but a different issue shows up. That’s what we’ll get into next.

Why The UI Feels Unstable And How To Fix It

If you tried the chat demo and scrolled upward while the responses were coming in, you may have spotted the first issue right away: the UI keeps pulling you back down to the latest streamed content as it updates. This takes you out of context and never allows you the time to fully digest the content once it has passed.

We see that exact same issue in the second example, the log viewer. Without the tail toggle, the streamed content overrides your scroll position.

These aren’t bugs in the traditional sense that they produce code errors; rather, they are accessibility issues that affect all users. That said, they can be fixed and prevented with careful UX considerations as you plan and test your work.

Ensure Predictable Scroll Behavior

This is the goal:

• Enable auto-scrolling when detecting that the user is at the bottom of the stream.
• Stop auto-scrolling when the user has scrolled upwards.
• Resume auto-scrolling if the user scrolls back to the bottom of the stream.

To do that, we need to know whether the user has intentionally moved away from the bottom, which we can assume is true when the scroll position is manually changed. We can track that behavior with a flag.

let userScrolled = false;

chatEl.addEventListener('scroll', () => {
  const gap = chatEl.scrollHeight
            - chatEl.scrollTop
            - chatEl.clientHeight;

  userScrolled = gap > 60;
});

That 60px threshold matters. Without it, tiny layout changes (like a new line) would briefly create a gap and break auto-scroll, even if the user didn’t actually scroll.

Now let’s make sure that we enable auto-scrolling only when the user’s scroll position is equal to the stream’s scroll height, i.e., the user is at the bottom of the stream:

function autoScroll() {
  if (!userScrolled) {
    chatEl.scrollTop = chatEl.scrollHeight;
  }
}

One small thing that’s easy to miss: we need to reset userScrolled once a new stream begins. Otherwise, one scroll from a previous message can silently disable auto-scroll for the next one.

Solidify Layout Stability

We saw this in the first example as well. As new content streams in, the layout jumps, or shifts, taking you out of your current context. To be specific about what’s shifting: it’s not the page layout in a broad sense, it’s the content directly below the chat bubble.

There’s also a subtler artifact worth calling out before we look at the code: cursor flicker. Because we’re wiping innerHTML and recreating every element on every tick, the cursor is being destroyed and re-added constantly, up to 80 times per second at fast speeds.

At normal speed, it’s easy to miss, but slow the slider down to around 30ms, and you’ll see a faint but persistent flicker at the end of the text. Once we fix the rebuild pattern, the flicker disappears entirely.

That rebuild pattern is right here; this is what runs on every single incoming character:

bubble.innerHTML = '';

fullText.split('\n').forEach(line => {
  const p = document.createElement('p');
  p.textContent = line || '\u00A0';
  bubble.appendChild(p);
});

bubble.appendChild(cursorEl);

This works, but it’s expensive. Every update wipes the DOM and rebuilds it, forcing layout recalculation each time.

Now we write directly into a live node:

let currentP = null;

function initBubble(bubble, cursor) {
  currentP = document.createElement('p');
  currentP.appendChild(document.createTextNode(''));
  bubble.insertBefore(currentP, cursor);
}

What we can do next is to create one paragraph with an empty text node and insert it before the cursor. That gives us a live node we can write into directly.

Then, for each character that arrives:

function appendChar(char, bubble, cursor) {
  if (char === '\n') {
    currentP = document.createElement('p');
    currentP.appendChild(document.createTextNode(''));
    bubble.insertBefore(currentP, cursor);
  } else {
    currentP.firstChild.textContent += char;
  }
}

For a regular character, we extend the text node by one character. The browser doesn’t need to recalculate the layout for that; the text grew, but nothing moved. For a newline, we create a fresh paragraph and move currentP forward. Layout recalculates once for that new paragraph, and that’s it.

Render Frequency

This one is most visible in the first example, the chat UI. Even with scrolling and a layout fixed, we’re still writing to the DOM on every single incoming character.

When the stream is moving fast, you end up hammering the DOM with updates that don’t actually matter. The fix is straightforward: hold the incoming text in a buffer instead of writing it out immediately. Once you’ve collected enough, write it all to the DOM in one go; that’s what a flush is.

To pull this off, we keep a simple buffer and make sure we only schedule a single update at a time. When it fires, requestAnimationFrame takes everything that has built up and writes it to the DOM in one shot.

let pending   = '';
let rafQueued = false;

When a new character streams in, we then add it to the buffer. If no flush is scheduled yet, we queue one:

function onChar(char) {
  pending += char;

  if (!rafQueued) {
    rafQueued = true;
    requestAnimationFrame(flush);
  }
}

The rafQueued flag is important. Without it, every character would schedule its own frame, and you’d end up with dozens of unnecessary flushes.

When the flush fires, it drains the entire buffer in one pass:

function flush() {
  for (const char of pending) {
    appendChar(char);
  }
  pending   = '';
  rafQueued = false;
  autoScroll();
}

All the characters that arrive after the last frame are then rendered together, right before the browser paints them. Then we clear the buffer, reset the flag, and run auto-scroll once.

let userScrolled = false;

chatEl.addEventListener('scroll', () => {
  const gap = chatEl.scrollHeight
            - chatEl.scrollTop
            - chatEl.clientHeight;

  userScrolled = gap > 60;
});

function autoScroll() {
  if (!userScrolled) {
    chatEl.scrollTop = chatEl.scrollHeight;
  }
}

If the gap is small, we keep auto-scrolling. If it grows, we assume the user scrolled up, and we stop. That small threshold helps avoid jitter when new lines slightly change the height. Also, remember to reset userScrolled when a new stream starts.

Once scrolling is under control, another issue becomes obvious. As the message grows, it keeps shifting:

• It starts as one line,
• It expands, then
• It pushes everything below it.

Nothing is technically broken, but it doesn’t feel stable. A common approach is to rebuild the whole message on every update:

bubble.innerHTML = '';

fullText.split('\n').forEach(line => {
  const p = document.createElement('p');
  p.textContent = line || '\u00A0';
  bubble.appendChild(p);
});

bubble.appendChild(cursorEl);

This works, but it is doing too much work. Every update destroys and rebuilds the DOM, forcing layout recalculation each time. That’s why everything keeps shifting. The idea is to write into the current paragraph and only create a new one when we actually hit a line break.

let currentP = null;

function initBubble(bubble, cursor) {
  currentP = document.createElement('p');
  currentP.appendChild(document.createTextNode(''));
  bubble.insertBefore(currentP, cursor);
}

And then update it character by character:

function appendChar(char, bubble, cursor) {
  if (char === '\n') {
    currentP = document.createElement('p');
    currentP.appendChild(document.createTextNode(''));
    bubble.insertBefore(currentP, cursor);
  } else {
    currentP.firstChild.textContent += char;
  }
}

Now we’re no longer rebuilding everything. Most updates just extend a text node, which is cheap and doesn’t trigger large layout shifts. It also fixes the small cursor flicker you might have noticed earlier, since we’re no longer removing and re-adding it.

At this point, the UI already feels better, but there is still something subtle going on. We are still updating the DOM on every character. At higher speeds, that becomes a lot of small updates, many of which you never actually see.

Instead of rendering immediately, we can buffer the incoming characters and apply them once per frame.

let pending = '';
let rafQueued = false;

function onChar(char) {
  pending += char;

  if (!rafQueued) {
    rafQueued = true;
    requestAnimationFrame(flush);
  }
}

At this point, we’re not touching the DOM yet, but only collecting characters as they arrive. Then, right before the next frame is painted, we flush everything at once:

function flush() {
  for (const char of pending) {
    appendChar(char);
  }

  pending = '';
  rafQueued = false;

  autoScroll();
}

These separate two things that were previously tied together:

1. How fast data arrives, and
2. When the UI updates.

The result looks the same, but the browser does less work, resulting in the UI feeling smoother, especially when the stream is set to a faster speed.

None of these changes is a big effort on its own. But once they are in place, the interface stops reacting blindly to every update. It becomes easier to read, easier to control, and a lot less distracting, even though the content is still coming in continuously.

There are even more considerations to take into account for ensuring a stable, predictable, and good user experience. For example, what happens if the stream is canceled mid-flow? And what can we do to ensure that user preferences are respected for things like reduced motion, keyboard navigation, and screen reader accessibility? Let’s get into those next.

Handling Interrupted Streams

Most streaming interfaces include a way to stop or cancel the stream. We saw that in the demos. But stopping often leaves the UI in an awkward state. The cursor might keep blinking, buttons don’t update, and the message just freezes mid-stream with no clear indication that it didn’t finish.

The problem is that the stop is usually wired to do one thing: cancel the timer. That’s not enough. You also need to (1) clear the pending buffer, (2) remove the cursor, (3) mark the response as incomplete, and (4) reset the buttons. Here’s how we accomplish those.

1. Stop The Stream Cleanly

Here’s what stopStream needs to do, in order:

1. Cancel the timer and flip the isStreaming flag so no more ticks run.
2. Clear the requestAnimationFrame (RAF) buffer so nothing still queued gets written on the next frame.

function stopStream() {
  clearTimeout(streamTimer);
  isStreaming = false;
  pending     = '';
  rafQueued   = false;
}

Clearing the pending property matters because there might be characters buffered from the last stream instance that haven’t been flushed yet. If you don’t clear it, the next requestAnimationFrame fires, drains the buffer, and writes those characters to the DOM after the stream has officially stopped.

Now we move on to removing the cursor by calling markStopped on the bubble:

if (cursorEl && cursorEl.parentNode) cursorEl.remove();
  markStopped(aiBubble);

  stopBtn.style.display  = 'none';
  retryBtn.style.display = '';
  playBtn.style.display  = '';
  setStatus('Stopped', 'stopped');
  chat.removeEventListener('scroll', onScroll);
}

The cursorEl.parentNode check is there because stopStream is also called internally when a new message fires mid-stream, at which point the cursor might already be gone. Calling remove() on a detached node throws, so we check first.

markStopped appends a small label to the bottom of the bubble so the user knows the response didn’t finish:

function markStopped(bubble) {
  if (!bubble) return;
  bubble.classList.add('stopped');

  const label = document.createElement('span');
  label.className = 'stopped-label';
  label.textContent = 'response stopped';
  bubble.appendChild(label);
}

The null check on bubble handles the edge case where stop fires before the AI message element has been initialized, which can happen if the user clicks stop during the 300ms delay before the bubble appears.

Provide A Retry Option

If the stream simply stops — perhaps due to a network issue or some other unexpected error — we ought to provide the user with a path to re-attempt the stream. What that basically means is preventing the UI from doing the expensive work needed to scroll back up to the top, re-read the prompt, and retype it. With a retry option, the user only needs to click a button, and the stream restarts from the current position.

To make that work, we need to hold onto the question when the stream starts:

let lastQuestion = '';

function startStream(question, answer) {
  lastQuestion = question;
  // rest of setup...
}

Then, when the retry attempt runs, we reset everything and start fresh:

function retryStream() {
  if (currentMsgEl && currentMsgEl.parentNode) {
    currentMsgEl.remove();
  }

  charIndex    = 0;
  userScrolled = false;
  pending      = '';
  rafQueued    = false;
  isStreaming  = true;

  retryBtn.style.display = 'none';
  stopBtn.style.display  = '';
  setStatus('Streaming...', 'streaming');

  chat.addEventListener('scroll', onScroll, { passive: true });

  setTimeout(() => {
    initAIMsg();
    tick(lastAnswer);
  }, 200);
}

The reset is critical. Every piece of state needs to go back to its initial value, just like a brand new stream.

Note: We remove the entire message row (currentMsgEl), not just the bubble. If only the bubble is removed, the layout wrapper and avatar remain persistent and break the structure.

Send A New Message Mid-Stream

There’s one more edge case that’s easy to miss. If the user sends a new message while a stream is still running, you end up with two loops writing to the DOM at the same time. The result is messy, and characters from different responses get mixed together.

Here’s what to do: stop the current stream before starting a new one.

function startStream(question, answer) {
  if (isStreaming) {
    clearTimeout(streamTimer);
    isStreaming = false;
    pending     = '';
    rafQueued   = false;
    if (cursorEl && cursorEl.parentNode) cursorEl.remove();
    chat.removeEventListener('scroll', onScroll);
  }

  // now reset and start fresh
  charIndex    = 0;
  userScrolled = false;
  isStreaming  = true;
  lastQuestion = question;
  // ...
}

Here, we inline the cleanup rather than calling stopStream directly because stopStream also calls markStopped and resets the buttons. The next demo has all three behaviors wired up. You can start a stream, hit “Stop” mid-stream, and the cursor disappears, the “response stopped” label appears, and a “Retry” buttons displayed.

Accessibility

Streaming interfaces are often built and tested with a mouse, so they may feel just fine in a browser, but break down in other situations that may not have been considered, like whether a screen reader announces new content at all. Or navigating with a keyboard might get stuck or lose focus as things update. And, of course, moving text can be uncomfortable — or even disabling — for those with motion sensitivities.

The good part is that you do not need to rebuild everything to accommodate these things; they can be fixed with solutions that sit on top of what is already there.

Accommodating Assistive Technology With Live Regions

Screen readers don’t automatically announce content that shows up on its own. They usually read things when the user moves to them. So, in a streaming UI, where text builds up over time, nothing gets announced. The content is there, but the user doesn’t hear anything.

The fix is aria-live. It tells the browser to watch a container and announce updates as they happen, without the user needing to move focus.

<div
  id="chat"
  role="log"
  aria-live="polite"
  aria-atomic="false"
  aria-label="Chat messages"
></div>

• role="log" tells assistive tech this is a stream of updates, like a running transcript. Some tools handle this automatically, but it’s safer to be explicit so behavior stays consistent.
• aria-atomic="false" makes sure only the new content is announced. Without it, some screen readers try to read the whole message again on every update, which quickly becomes unusable.
• aria-live="polite" queues updates instead of interrupting. Use assertive only for things that really need immediate attention, like errors.

Handling Incomplete States

Earlier, we inserted a “Response Stopped” label to the message when the stream stops mid-stream. Visually, that’s enough. But for a screen reader, that change needs to be announced.

Since the message is inside a live region with aria-live="polite", the label will be automatically announced as new content when it’s added to the DOM. The live region already handles the announcement, so no additional ARIA is needed on the label itself.

The Retry button that appears next also needs context. If a screen reader simply says “Retry, button,” it’s not clear what action that refers to. You can fix that by adding an aria-label that includes the original question:

retryBtn.setAttribute(
  'aria-label',
  `Retry: ${lastQuestion.slice(0, 60)}`
);

What you can do here is to set this label when the button appears, not on page load:

retryBtn.style.display = 'inline-block';
retryBtn.setAttribute(
  'aria-label',
  `Retry: ${lastQuestion.slice(0, 60)}`
);

We also call retryBtn.focus() after stopping. That way, keyboard users don’t have to Tab around with the keyboard to find the next action.

Testing with assistive technology: Don’t rely on assumptions about how screen readers announce this. Test with actual tools like NVDA (Windows), JAWS (Windows), or VoiceOver (Mac/iOS). Browser DevTools can show you what’s exposed in the accessibility tree, but they can’t tell you how the content sounds. A real screen reader will reveal whether the announcement is happening at the right time and in the right way.

Account For Keyboard Navigation

The controls need to work with the keyboard while the UI is live, so the Stop button has to be reachable. For someone not using a mouse, Tab + Enter is the only way to cancel a running stream.

Using display: none is fine for hiding buttons; it removes them from the tab order. The problem is using things like opacity: 0 or visibility: hidden. Those hide elements visually, but they can still receive focus, so users end up tabbing onto something they can’t see.

Use :focus-visible so the focus ring shows up for keyboard navigation, but not for mouse clicks:

btn:focus-visible {
  outline: 2px solid #1d9e75;
  outline-offset: 2px;
}

The cursor inside the message should have aria-hidden="true". It’s just visual. Without that, some screen readers try to read it as text, which gets distracting.

Motion Sensitivity

The typewriter effect we see in practically every AI interface produces constant motion. As we’ve already discussed, certain amounts of motion can be disabling. Thankfully, browsers expose prefers-reduced-motion, which detects a user’s motion preferences at the operating system level.

For streaming, the best approach is simple: skip the animation and render the full response at once. The content stays the same, only without the motion.

const reducedMotion = window.matchMedia(
  '(prefers-reduced-motion: reduce)'
).matches;

if (reducedMotion) {
  initAIMsg();
  for (const char of text) appendChar(char);
  if (cursorEl && cursorEl.parentNode) cursorEl.remove();
  done();
  return;
}
tick(text); // normal animation

In CSS, the cursor blink also needs to stop. Despite being a minor detail, a blinking cursor element counts as flashing content.

@media (prefers-reduced-motion: reduce) {
  .cursor { animation: none; opacity: 1; }
}

There we go! The demo below puts everything from this article together, so you can see how these patterns work in practice. It also includes a reduced motion toggle, so you can test the instant render version easily.

Conclusion

Streaming itself is mostly solved. Getting data from the server to the client is not the hard part anymore. What breaks is the UI on top of it.

When content updates continuously, small things start to matter, like scroll behavior, layout stability, render timing, and how the interface responds to user actions. If those aren’t handled well, the UI feels unstable and hard to use.

The patterns in this article fix that by:

• Keeping scroll position under the user’s control,
• Updating only what has changed,
• Batching renders per frame,
• Handling stop and retry actions, and
• Making the interface accessible.

You don’t need all of these every time. But when streaming is involved, these are the places things usually go wrong.

Further Reading

• Using Server-Sent Events
  How to open a connection, handle events, and reconnect when needed. This is the transport layer, everything here builds on.
• Streams API
  Streaming data directly from fetch. Useful when you need more control than SSE.
• Chrome DevTools Performance panel
  Helps you see layout recalculations and paint costs, so you can verify performance improvements.
• “How Large DOM Sizes Affect Interactivity, And What You Can Do About It”, Jeremy Wagner
  Why large DOM trees slow things down, and how to keep them under control in long streaming sessions.

(yk)

We often see design principles as rigid guidelines that dictate design decisions. But actually, they are an incredible tool to rally the team around a shared purpose and document the values and beliefs that an organization embodies.

They align teams and inform decision-making. They also keep us afloat amidst all the hype, big assumptions, desire for faster delivery, and AI workslop. But how do we choose the right ones, and how do we get started? Let’s find out.

Real-World Design Principles

In times when we can generate any passable design and code within minutes, we need to decide better what’s worth designing and building — and what values we want our products to embody.

It’s similar to voice and tone. You might not design it intentionally, but then end users will define it for you. And so, without principles, many company initiatives are random, sporadic, ad-hoc — and feel vague, inconsistent, or simply dull to the outside world.

Design principles are guidelines and design considerations that designers apply with discretion — by default, without debating or discussing what has already been agreed upon.

One fantastic resource that I keep coming back to after all these years is Ben Brignell’s Principles.design. It has 230 pointers for design principles and methods, searchable and tagged, covering everything from language and infrastructure to hardware and organizations.

10 Principles Of Good Design

There is no shortage of principles out there. But the good ones are more than just being visionary — they have a point of view, and they explain what we don’t do as much as what we do. They also explain what we stand for in the world — beyond profits, stock prices, and all the hype and noise around us.

Many years ago, I encountered Dieter Rams’ 10 principles of good design (see above), a very humble, practical and tangible overview of principles that were informing, shaping, and guarding his design work at Braun.

There are no visionary claims, and no big bold statements: just a clear overview of what we do, and where our ambition and care lie for the products we are designing. It’s honest, sincere, and in many ways beautifully humane.

Examples Of Design Principles

There are plenty of wonderful examples that I keep close:

• Anthropic’s Constitution
• Principles of Product Design, by Joshua Porter
• Guiding Principles for Experience Design, by Whitney Hess, PCC
• Principles of Web Accessibility, by Heydon Pickering
• Humane by Design, by Jon Yablonski
• Designing Voice UX Principles, by Brian Colcord
• Agentic Design Principles, by Linear
• AI Chatbot Design Principles, by Emmet Connolly
• Voice UX Principles, by Ben Sauer

Design Principles In Design Systems

• 18F
• Audi
• Carbon (IBM)
• Firefox
• Gov.uk
• Intuit
• NHS
• Nordhealth
• Uber

How To Establish Design Principles

Design principles can be personal, but usually they are committed to and shaped by the entire product team. Design principles aren’t just for designers. User’s experience is everything from performance to support to customer service, and ideally, participants would cover these areas as well.

In practice, though, establishing principles might feel incredibly challenging. They are abstract and fluffy and often ambiguous, and often very difficult to agree upon.

You can get started with a simple 8-step workshop (inspired by Marcin Treder, Maria Meireles and Better):

1. Pre-session Research
   Study how users speak about the products, what they appreciate, and the words they use.
2. Get Into Principles Mode
   Invite 6–8 participants, ask them to choose their favorite object, and describe it in 3 words.
3. Product Analogies
   Compare product to tangible items (e.g., ‘A Porsche 911’ or ‘a Braun audio system’).
4. Extract Attributes
   Individually, in silence, everyone writes 3–5 initial principles, which are then grouped by theme for review.
5. Link Attributes To Research
   Link attributes to actual user pain points or desires, to make sure they are grounded in reality.
6. Value Statements
   We write ‘We want X because of Y’ sentences that express the rationale behind our thinking.
7. Move to Principles
   Remove analogies to create enduring rules that will guide our design process.
8. Reality Check
   Search for both positive and negative examples in our products to see where principles are being met or ignored.

Useful Starter Kits For Principles Workshops

• Design Principles Workshop (Figma Template), by Maria Meireles
• Design Principles Workshop (FigJam Template), by Richard Picot
• How to Create Design Principles (Miro Workshop Template), by NanoGiants

Wrapping Up

Creating principles is only a small portion of the work; most work is about effectively sharing and embedding them. It’s difficult to get anywhere without finding ways to make design principles a default — by revisiting settings, templates, naming conventions, and output.

Principles help avoid endless discussions that often stem from personal preferences or taste. But design should not be a matter of taste; it must be guided by our goals and values. Design principles can help with just that.

Meet “Design Patterns For AI Interfaces”

Meet Design Patterns For AI Interfaces, Vitaly’s new video course with 100s of real-life examples and UX guidelines to design AI features that people actually use — with a live UX training later this year. Jump to a free preview.

Useful Resources

• Design Principles Collection, by Ben Brignell
• “How To Establish Design Principles”, by Marcin Treder
• “Establishing Design Principles for a Design System and What It Taught Us”, by Better Design Team
• Design Principles, by Jeremy Keith
• Design Principles Collection, by Gabriel Svennerberg
• Design Principles Workshop (Figma Template), by Maria Meireles
• Design Principles Workshop (FigJam Template), by Richard Picot
• How to Create Design Principles (Miro Workshop Template), by NanoGiants
• Modals in Design Systems

(yk)

You probably have been there before. How do we choose between showing a modal to users, and when do we navigate them to a separate, new page? And does it matter at all?

Actually, it does. The decision influences users’ flow, their context, their ability to look up details, and with it error frequency and task completion. Both options can be disruptive and frustrating — at the wrong time, and at the wrong place.

So we’d better get it right. Well, let’s see how to do just that.

Modals vs. Dialogs vs. Overlays vs. Lightboxes

While we often speak about a single modal UI component, we often ignore fine, intricate nuances between all the different types of modals. In fact, not every modal is the same. Modals, dialogs, overlays, and lightboxes — all sound similar, but they are actually quite different:

• Dialog
  A generic term for “conversation” (user ↔ system).
• Overlay
  A small content panel displayed on top of a page.
• Modal
  User must interact with overlay + background disabled.
• Nonmodal
  User must interact with overlay + background enabled.
• Lightbox
  Dimmed background to focus attention on the modal.

As Anna Kaley highlights, most overlays appear at the wrong time, interrupt users during critical tasks, use poor language, and break users’ flow. They are interruptive by nature, and typically with a high level of severity without a strong need for that.

Surely users must be slowed down and interrupted if the consequences of their action have a high impact, but for most scenarios non-modals are much more subtle and a more friendly option to bring something to the user’s attention. If anything, I always suggest it to be a default.

Modals → For Single, Self-Contained Tasks

As designers, we often dismiss modals as irrelevant and annoying — and often they are! — yet they have their value as well. They can be very helpful to warn users about potential mistakes or help them avoid data loss. They can also help perform related actions or drill down into details without interrupting the current state of the page.

But the biggest advantage of modals is that they help users keep the context of the current screen. It doesn’t mean just the UI, but also edited input, scrolling position, state of accordions, selection of filters, sorting, and so on.

At times, users need to confirm a selection quickly (e.g., filters as shown above) and then proceed immediately from there. Auto-save can achieve the same, of course, but it’s not always needed or desired. And blocking the UI is often not a good idea.

However, modals aren’t used for any tasks. Typically, we use them for single, self-contained tasks where users should jump in, complete a task, and then return to where they were. Unsurprisingly, they do work well for high-priority, short interactions (e.g., alerts, destructive actions, quick confirmations).

When modals help:

🚫 Modals are often disruptive, invasive, and confusing.
🚫 They make it difficult to compare and copy-paste.
✅ Yet modals allow users to maintain multiple contexts.
✅ Useful to prevent irreversible errors and data loss.
✅ Useful if sending users to a new page would be disruptive.

✅ Show a modal only if users will value the disruption.
✅ By default, prefer non-blocking dialogs (“nonmodals”).
✅ Allow users to minimize, hide, or restore the dialog later.
✅ Use a modal to slow users down, e.g., verify complex input.
✅ Give a way out with “Close”, ESC key, or click outside the box.

Pages → For Complex, Multi-Step Workflows

Wizards or tabbed navigation within modals doesn’t work too well, even in complex enterprise products — there, side panels or drawers typically work better. Troubles start when users need to compare or reference data points — yet modals block this behavior, so they re-open the same page in multiple tabs instead.

For more complex flows and multi-step processes, standalone pages work best. Pages also work better when they demand the user’s full attention, and reference to the previous screen isn’t very helpful. And drawers work for sub-tasks that are too complex for a simple modal, but don’t need a full page navigation.

When to avoid modals:

🚫 Avoid modals for error messages.
🚫 Avoid modals for feature notifications.
🚫 Avoid modals for onboarding experience.
🚫 Avoid modals for complex, lengthy multi-step-tasks.
🚫 Avoid multiple nested modals and use prev/next instead.
🚫 Avoid auto-triggered modals unless absolutely necessary.

Avoid Both For Repeated Tasks

In many complex, task-heavy products, users will find themselves performing the same tasks repeatedly, over and over again. There, both modals and new page navigations add friction because they interrupt the flow or force users to gather missing data between all the different tabs or views.

Too often, users end up with a broken experience, full of never-ending confirmations, exaggerated warnings, verbose instructions, or just missing reference points. As Saulius Stebulis mentioned, in these scenarios, expandable sections or in-place editing often work better — they keep the task anchored to the current screen.

In practice, in many scenarios, users don’t complete their tasks in isolation. They need to look up data, copy-paste values, refine entries in different places, or just review similar records as they work through their tasks.

Overlays and drawers are more helpful in maintaining access to background data during the task. As a result, the context always stays in its place, available for reference or copy-paste. Save modals and page navigation for moments where the interruption genuinely adds value — especially to prevent critical mistakes.

Modals vs. Pages: A Decision Tree

A while back, Ryan Neufeld put together a very helpful guide to help designers choose between modals and pages. It comes with a handy PNG cheatsheet and a Google Doc template with questions broken down across 7 sections.

It’s lengthy, extremely thorough, but very easy to follow:

It might look daunting, but it’s a quite simple 4-step process:

1. Context of the screen.
   First, we check if users need to maintain the context of the underlying screen.
2. Task complexity and duration.
   Simpler, focused, non-distracting tasks could use a modal, but long, complex flows need a page.
3. Reference to underlying page.
   Then, we check if users often need to refer to data in the background or if the task is a simple confirmation or selection.
4. Choosing the right overlay.
   Finally, if an overlay is indeed a good option, it guides us to choose between modal or nonmodal (leaning towards a nonmodal).

Wrapping Up

Whenever possible, avoid blocking the entire UI. Have a dialog floating, partially covering the UI, but allowing navigation, scrolling, and copy-pasting. Or show the contents of the modal as a side drawer. Or use a vertical accordion instead. Or bring users to a separate page if you need to show a lot of detail.

But if you want to boost users’ efficiency and speed, avoid modals at all costs. Use them to slow users down, to bundle their attention, to prevent mistakes. As Therese Fessenden noted, no one likes to be interrupted, but if you must, make sure it’s absolutely worth the cost.

Meet “Smart Interface Design Patterns”

You can find a whole section about modals and alternatives in Smart Interface Design Patterns, our 15h-video course with 100s of practical examples from real-life projects — with a live UX training later this year. Everything from mega-dropdowns to complex enterprise tables — with 5 new segments added every year. Jump to a free preview. Use code BIRDIE to save 15% off.

Useful Resources

• Different Types of Popups, by Anna Kaley
• Best Practices for Designing UI Modals, by Uxcel
• We Use Too Many Damn Modals: UX Guidelines, by Adrian Egger
• Modal & Nonmodal Dialogs, by Therese Fessenden
• Modern Enterprise UI Design: Modal Dialogs, by James Jacobs
• Modals in Design Systems

(yk)

When I first started building websites, rounded corners required five background images, one for each corner, one for the body, and a prayer that the client wouldn’t ask for a different radius. Then the border-radius property landed, and the entire web collectively sighed with relief. That was over fifteen years ago, and honestly, we’ve been riding that same wave ever since. Just as then, I hope that we can look at this feature as a progressive enhancement slowly making its way to other browsers.

I like a good border-radius like any other guy, but the fact is that it only gives us one shape. Round. That’s it. Want beveled corners? Clip-path. Scooped ticket edges? SVG mask. Squircle app icons? A carefully tuned SVG that you hope nobody asks you to animate. We’ve been hacking around the limitations of border-radius for years, and those hacks come with real trade-offs: borders don’t follow clip-paths, shadows get cut off, and you end up with brittle code that breaks the moment someone changes a padding value.

Well, the new corner-shape changes all of that.

What Is corner-shape?

The corner-shape property is a companion to border-radius. It doesn’t replace it; it modifies the shape of the curve that border-radius creates. Without border-radius, corner-shape does nothing. But together, they’re a powerful pair.

The property accepts these values:

• round: the default, same as regular border-radius,
• squircle: a superellipse, the smooth Apple-style rounded square,
• bevel: a straight line between the two radius endpoints (snipped corners),
• scoop: an inverted curve, creating concave corners,
• notch: sharp inward cuts,
• square: effectively removes the rounding, overriding border-radius.

And you can set different values per corner, just like border-radius:

*corner-shape: bevel round scoop squircle;
/* top-left, top-right, bottom-right, bottom-left */

You can also use the superellipse() function with a numeric parameter for fine-grained control.

.element { 
  border-radius: 25px;
  corner-shape: superellipse(0); /* equal to 'bevel' */
}

So the question here might be: why not call this property “border-shape” instead? Well, first of all, that is something completely different that we’ll get to play around with soon. Second, it does apply to a bit more than borders, such as outlines, box shadows, and backgrounds. That’s the thing that the clip-path property could never do.

Why Progressive Enhancement Matters Here

At the time of writing (March 2026), corner-shape is only supported in Chrome 139+ and other Chromium-based browsers. That’s a significant chunk of users, but certainly not everyone. The temptation is to either ignore the property until it’s everywhere or to build demos that fall apart without it.

I don’t think either approach is right. The way I see it, corner-shape is the perfect candidate for progressive enhancement, just as border-radius was in the age of Internet Explorer 6. The baseline should use the techniques we already know, such as border-radius, clip-path, radial-gradient masks and look intentionally good. Then, for browsers that support corner-shape, we upgrade the experience. Sometimes this can be as simple as just providing a more basic default; sometimes it might need to be a bit more.

Every demo in this article is created with that progressive enhancement idea. The structure for the demos looks like:

@layer base, presentation, demo;

The presentation layer contains the full polished UI using proven techniques. The demo layer wraps everything in @supports:

@layer demo {
  @supports (corner-shape: bevel) {
    /* upgrade styles here */
  }
}

No fallback banners, no “your browser doesn’t support this” messages. Just two tiers of design: good and better. I thought it could be nice just to show some examples. There are a few out there already, but I hope I can add a bit of extra inspiration on top of those.

Demo 1: Product Cards With Ribbon Badges

Every e-commerce site has them: those little “New” or “Sale” badges pinned to the corner of a product card. Traditionally, getting that ribbon shape means reaching for clip-path: polygon() or a rotated pseudo-element, let’s call it “fiddly code” that has the chance to fall apart the moment someone changes a padding value.

But here’s the thing: we don’t need the ribbon shape in the baseline. A simple badge with slightly rounded corners tells the same story and looks perfectly fine:

.product__badge {
  border-radius: 0 4px 4px 0;
  background-color: var(--badge-bg);
}

That’s it. A small, clean label sitting flush against the left edge of the card. Nothing fancy, nothing broken. It works in every browser.

For browsers that support corner-shape, we enhance:

@layer demo {
  /* If the browser supports `corner-shape` */
  @supports (corner-shape: bevel) {
    .product {
      border-radius: 40px;
      corner-shape: squircle;
    }

    .product__badge {
      padding: 0.35rem 1.4rem 0.35rem 1rem;
      border-radius: 0 16px 16px 0;
      corner-shape: round bevel bevel round;
    }
  }
}

The round bevel bevel round combination creates a directional ribbon. Round where it meets the card edge, beveled to a point on the other side. No clip-path, no pseudo-element tricks. Borders, shadows, and backgrounds all follow the declared shape because it is the shape.

The cards themselves upgrade from border-radius: 12px to a larger size and the squircle corner-shape, that smooth superellipse curve that makes standard rounding look slightly off by comparison. Designers will notice immediately. Everyone else will just say it “feels more premium.”

Hot tip: Using the squircle value on card components is one of those upgrades where the before-and-after difference can be subtle in isolation, but transformative across an entire page. It’s the iOS effect: once everything uses superellipse curves, plain circular arcs start looking out of place. In this demo, I did exaggerate a bit.

Demo 2: Buttons, Tags, And Components

This is the “component library demo”, the one that shows corner-shape isn’t just for hero sections. It’s practical, everyday UI: solid buttons, outlined buttons, status tags, directional arrows, notification badges.

The set-up is intentionally clean. Standard border-radius: 10px buttons with a polished typeface. Everything works, everything looks professional. You could do this without hesitation.

The corner-shape layer turns it into a showcase. Each button type gets its own shape to demonstrate the range of what’s possible:

@layer demo {
  @supports (corner-shape: bevel) {
    .btn--primary {
      corner-shape: bevel;
      transition: corner-shape 0.3s ease;

      &:hover {
        corner-shape: squircle;
      }
    }

    .btn--secondary {
      border-radius: 25px;
      corner-shape: superellipse(0.5);
    }

    .btn--danger {
      border-radius: 16px;
      corner-shape: squircle;
    }

    .btn--notch {
      border-radius: 12px;
      corner-shape: notch;
    }

    .btn--scoop {
      border-radius: 14px;
      corner-shape: scoop;
    }
  }
}

The primary button starts beveled, faceted, and gem-like, and softens to squircle on hover. Because corner-shape values animate via their superellipse() equivalents, the transition is smooth. It’s a fun interaction that used to be hard to achieve but is now a single property (used alongside border-radius, of course).

The secondary button uses superellipse(0.5), a value that is between a standard circle and a squircle, combined with a larger border-radius for a distinctive pill-like shape. The danger button gets a more prominent squircle with a generous radius. And notch and scoop each bring their own sharp or concave personality.

Beyond buttons, the status tags get corner-shape: notch, those sharp inward cuts that give them a machine-stamped look. The directional arrow tags use round bevel bevel round (and its reverse for the back arrow), replacing what used to require clip-path: polygon(). Now borders and shadows work correctly across all states.

Demo 3: Testimonial Cards

This demo is probably my favourite one. At its foundation, these are just testimonial cards with serif typography, a sandy palette, and scooped corners on the featured card. The design language is intentionally different from the clean geometric buttons demo, and that’s the point. corner-shape merely adds that extra “edge”.

The basis is standard border-radius: 16px cards. The featured testimonial spans full width with a subtle gradient and a decorative open quote mark. Normal cards alternate in a two-column grid. It already looks like something from a premium marketing site.

The corner-shape layer adds character:

@layer demo {
  /* Progressive enhancement */
  @supports (corner-shape: scoop) {
    .testimonial {
      border-radius: 20px;
      corner-shape: squircle;
    }

    .testimonial--featured {
      border-radius: 24px;
      corner-shape: scoop;
    }

    .testimonial:not(.testimonial--featured):nth-child(even) {
      corner-shape: scoop round;
    }

    .testimonial__avatar {
      border-radius: 28%;
      corner-shape: squircle;
    }
  }
}

The featured card gets full scoop corners, concave on all four sides, creating an organic, almost hand-crafted feel that matches the serif typography. Even-numbered cards mix scoop round, giving each one a slightly different personality without any extra markup.

The author avatars switch from circles to squircle. A small touch that makes it a bit more “different”.

Hot tip: corner-shape: scoop pairs beautifully with serif fonts and warm color palettes. The concave curves echo the organic shapes found in editorial design, calligraphy, and print layouts. For geometric sans-serif designs, stick with squircle or bevel.

Demo 4: Pricing Cards

Every SaaS site needs a pricing page, and the visual hierarchy challenge is always the same: make one plan stand out without the others feeling neglected. This demo solves it with corner-shape.

This is quite similar to the last demo in that we once again have a nice baseline for browsers that don’t yet support corner-shape. We have three cards in a row, where the featured plan is distinguished by a warm gradient background, a stronger border, and a “Most Popular” badge.

The enhancement takes it further:

@layer demo {
  @supports (corner-shape: squircle) {
    .plan {
      border-radius: 20px;
      corner-shape: squircle;
    }

    .plan--featured {
      border-radius: 24px;
      corner-shape: scoop;
    }

    .plan__badge {
      inset-inline-start: 50%;
      translate: -50% 0;
      padding-inline: 1.2rem;
      border-radius: 10px;
      corner-shape: bevel;
    }

    .plan__cta {
      border-radius: 12px;
      corner-shape: squircle;
    }
  }
}

Regular plans get squircle for that premium feel. The featured plan gets scoop, concave corners that immediately set it apart from its neighbors. The “Most Popular” badge centers itself and takes on corner-shape: bevel, creating a gem-like, faceted shape that feels like a jewel pinned to the card. The CTA buttons get squircle to match the card language.

What I like about this demo is how the shape hierarchy mirrors the content hierarchy. The most important element (featured plan) gets the most distinctive shape (scoop). The badge gets the sharpest shape (bevel). Everything else gets a simpler upgrade (squircle). Shape becomes a tool for visual emphasis, not just decoration.

Demo 5: Music Player

The final demo is a warm dark UI for a music player with album art, playback controls, genre tags, and a listening queue. It’s the most visually complex demo, and it shows how corner-shape works across many different element types within a single cohesive design.

This time, I went for a dark warm palette built on oklch(18% 0.015 40), and standard rounded corners throughout. The album art gets border-radius: 12px, queue items get border-radius: 12px, genre tags get border-radius: 5px. It looks good. It’s a complete, polished player.

And then once again, we add some enhancements:

@layer demo {
  @supports (corner-shape: squircle) {
    .now-playing {
      border-radius: 20px;
      corner-shape: squircle;
    }

    .now-playing__art {
      border-radius: 16px;
      corner-shape: squircle;
    }

    .now-playing__swatch {
      border-radius: 26%;
      corner-shape: squircle;
    }

    .queue-item {
      border-radius: 14px;
      corner-shape: scoop round;
    }

    .tag {
      border-radius: 8px;
      corner-shape: bevel;
    }
  }
}

The player card and album art get squircle, the same curves used for app icons and album thumbnails. Album art swatches go from border-radius: 22% to a proper squircle at 26%, which is a subtle but meaningful difference in the visual elements you stare at while listening.

Queue items get scoop round, resulting in concave corners on the top-left and bottom-left, and round on the right. It gives each row a distinctive feel without overwhelming the layout. Genre tags get bevel for that sharp feeling.

The Play button also gets corner-shape: squircle on its existing border-radius: 50% to fit the album covers. On the surface, the difference is barely noticeable, but it contributes to the overall feel of the player.

Browser Support

As of writing, corner-shape is available in Chrome 139+ and Chromium-based browsers. Firefox and Safari don’t support it yet. The spec lives in CSS Borders and Box Decorations Module Level 4, which is a W3C Working Draft as of this writing.

For practical use, that’s fine. That’s the whole point of how these demos are built. The presentation layer delivers a polished, complete UI to every browser. The demo layer is a bonus for supporting browsers, wrapped in @supports (corner-shape: ...). I lived through the time when border-radius was only available in Firefox. Somewhere along the line, it seems like we have forgotten that not every website needs to look exactly the same in every browser. What we really want is: no “broken” layouts and no “your browser doesn’t support this” messages, but rather a beautiful experience that just works, and can progressively enhance a bit of extra joy. In other words, we’re working with two tiers of design: good and better.

Wrapping Up

The approach I keep coming back to is: don’t design for corner-shape, and don’t design around the lack of it. Design a solid baseline with border-radius and then enhance it. The presentation layer in every demo looks intentionally good. It’s not a degraded version waiting for a better browser. It’s a complete design. The demo layer adds a dimension that border-radius alone can’t express.

What surprises me most about corner-shape is the range it offers — the amazing powerhouse we have with this single property: squircle for that premium, superellipse feel on cards and avatars; bevel for directional elements and gem-like badges; scoop for editorial warmth and visual hierarchy; notch for mechanical precision on tags; and superellipse() for fine control between round and squircle. And the ability to mix values per corner (round bevel bevel round, scoop round) opens up shapes that would have required SVG masks or clip-path hacks.

We went from five background images to border-radius, to corner-shape. Each step removed a category of workarounds. I’m excited to see what designers do with this one.

Further Reading

• corner-shape (MDN)
• “What Can We Actually Do With corner-shape?”, Daniel Schwarz
• CSS Borders and Box Decorations Module Level 4 (W3C specification)
• A fun demo for “eco-labels”, Sebastian on CodePen

(gg, yk)

So what’s the difference between combobox, multiselect, listbox, and dropdown? While all these UI components might appear similar, they serve different purposes. The choice often comes down to the number of available options and their visibility.

Let’s see how they differ, what purpose they serve, and how to choose the right one — avoiding misunderstandings and wrong expectations along the way.

Not All List Patterns Are The Same

All the UI components highlighted above have exactly one thing in common: they support users’ interactions with lists. However, they do so slightly differently.

Let’s take a look at each, one by one:

• Dropdown → list is hidden until it’s triggered.
• Combobox → type to filter + select 1 option.
• Multiselect → type to filter + select many options.
• Listbox → all list options visible by default (+ scroll).
• Dual listbox → move items between 2 listboxes.

In other words, Combobox combines a text input field with a dropdown list, so users can type to filter and select a single option. With Multiselect, users can select many options (often displayed as pills or chips).

Listboxes display all list options visible by default, often with scrolling. It’s helpful when users need to see all available choices immediately. Dual listbox (also called transfer list) is a variation of a listbox that allows users to move items between two listboxes (left ↔ right), typically for bulk selection.

Never Hide Frequently Used Options

As mentioned above, the choice of the right UI component depends on 2 factors: how many list options are available, and if all these options need to be visible by default. All lists could have tree structures, nesting, and group selection, too.

There is one principle that I’ve been following for years for any UI component: never hide frequently used options. If users rely on a particular selection frequently, there is very little value in hiding it from them.

We could either make it pre-selected, or (if there are only 2–3 frequently used options) show them as chips or buttons, and then show the rest of the list on interaction. In general, it’s a good idea to always display popular options — even if it might clutter the UI.

How To Choose Which?

Not every list needs a complex selection method. For lists with fewer than 5 items, simple radio buttons or checkboxes usually work best. But if users need to select from a large list of options (e.g., 200+ items), combobox + multiselect are helpful because of the faster filtering (e.g., country selection).

Listboxes are helpful when people need to access many options at once, especially if they need to choose many options from that list as well. They could be helpful for frequently used filters.

Dual listbox is often overlooked and ignored. But it can be very helpful for complex tasks, e..g bulk selection, or assigning roles, tasks, responsibilities. It’s the only UI component that allows users to review their full selection list side-by-side with the source list before committing (also called “Transfer list”).

In fact, dual listbox is often faster, more accurate, and more accessible than drag-and-drop.

Usability Considerations

One important note to keep in mind is that all list types need to support keyboard navigation (e.g., ↑/↓ arrow keys) for accessibility. Some people will almost always rely uponthe keyboard to select options once they start typing.

Beyond that:

• For lists with 7+ options, consider adding “Select All” and “Clear All” functionalities to streamline user interaction.
• For lengthy lists with a combobox, expose all options to users on click/tap, as otherwise they might never be seen,
• Most important, don’t display non-interactive elements as buttons to avoid confusion — and don’t display interactive elements as static labels.

Wrapping Up: Not Everything Is A Dropdown

Names matter. A vertical list of options is typically described as a “dropdown” — but often it’s a bit too generic to be meaningful. “Dropdown” hints that the list is hidden by default. “Multiselect” implies multi-selection (checkbox) within a list. “Combobox” implies text input. And “Listbox” is simply a list of selectable items, visible at all times.

The goal isn’t to be consistent with the definitions above for the sake of it. But rather to align intentions — speak the same language when deciding on, designing, building, and then using these UI components.

It should work for everyone — designers, engineers, and end users — as long as static labels don’t look like interactive buttons, and radio buttons don’t act like checkboxes.

Meet “Design Patterns For AI Interfaces”

Meet Design Patterns For AI Interfaces, Vitaly’s new video course with practical examples from real-life products — with a live UX training happening soon. Jump to a free preview.

Useful Resources

• Autocomplete: UX Guidelines, by Vitaly Friedman
• Combobox, by eBay 👍
• Combobox, by Elastic
• Combobox, by Elisa
• Combobox, by MongoDB 👍
• Combobox, by Visa 👍
• Combobox, by Watson (Docplanner)
• Combobox, by Wikimedia
• Combobox, by Zendesk
• Multiselect (MongoDB Combobox Design Docs), by MongoDB 👍
• Multiselect Lookup, by Wikimedia
• Multi-select Combo Box, by Vaadin
• Multiselect, by Visa
• Transfer (Listbox example), by Ant Design
• Listbox, by Hopper
• List Box, by Vaadin
• Listbox, by Visa
• Dual List Selector, by Red Hat (PatternFly)
• Dual Listbox, by Salesforce (Lightning Design System)
• Transfer List, by Mantine
• Dual Listbox, by Dashlite
• Badges vs. Pills vs. Chips vs. Tags, by Vitaly Friedman
• Listboxes vs. Dropdown Lists, by Anna Kaley (NN/g)

(yk)

This article is sponsored by Penpot

Since Brad Frost popularized the use of design systems in digital design way back in 2013, they’ve become an invaluable resource for organizations — and even individuals — that want to craft reusable design patterns that look and feel consistent.

But Brad didn’t just popularize design systems; he also gave us a framework for structuring them, and while we don’t have to follow that framework exactly (most people adapt it to their needs), a particularly important part of most design systems is the variants, which are variations of components. Component variants allow for the design of components that are the same as other components, but different, so that they’re understood by users immediately, yet provide clarity for a unique context.

This makes component variants just as important as the components themselves. They ensure that we aren’t creating too many components that have to be individually managed, even if they’re only mildly different from other components, and since component variants are grouped together, they also ensure organization and visual consistency.

And now we can use them in Penpot, the web-based, open-source design tool where design is expressed as code. In this article, you’ll learn about variants, their place in design systems, and how to use them effectively in Penpot.

Step 1: Get Your Design Tokens In Order

For the most part, what separates one variant from another is the design tokens that it uses. But what is a design token exactly?

Imagine a brand color, let’s say a color value equal to hsl(270 100 42) in CSS. We save it as a “design token” called color.brand.default so that we can reuse it more easily without having to remember the more cumbersome hsl(270 100 42).

From there, we might also create a second design token called background.button.primary.default and set it to color.brand.default, thereby making them equal to the same color, but with different names to establish semantic separation between the two. This referencing the value of one token from another token is often called an “alias”.

This setup gives us the flexibility to change the value of the color document-wide, change the color used in the component (maybe by switching to a different token alias), or create a variant of the component that uses a different color. Ultimately, the goal is to be able to make changes in many places at once rather than one-by-one, mostly by editing the design token values rather than the design itself, at specific scopes rather than limiting ourselves to all-or-nothing changes. This also enables us to scale our design system without constraints.

With that in mind, here’s a rough idea of just a few color-related design tokens for a primary button with hover and disabled states:

To create a color token in Penpot, switch to the “Tokens” tab in the left panel, click on the plus (+) icon next to “Color”, then specify the name, value, and optional description.

For example:

• Name: color.brand.default,
• Value: hsl(270 100 42) (there’s a color picker if you need it).

It’s pretty much the same process for other types of design tokens.

Don’t worry, I’m not going to walk you through every design token, but I will show you how to create a design token alias. Simply repeat the steps above, but for the value, notice how I’ve just referenced another color token (make sure to include the curly braces):

• Name: background.button.primary.default,
• Value: {color.brand.default}

Now, if the value of the color changes, so will the background of the buttons. But also, if we want to decouple the color from the buttons, all we need to do is reference a different color token or value. Mikołaj Dobrucki goes into a lot more detail in another Smashing article, but it’s worth noting here that Penpot design tokens are platform-agnostic. They follow the standardized W3C DTCG format, which means that they’re compatible with other tools and easily export to all platforms, including web, iOS, and Android.

In the next couple of steps, we’ll create a button component and its variants while plugging different design tokens into different variants. You’ll see why doing this is so useful and how using design tokens in variants benefits design systems overall.

Step 2: Create The Component

You’ll need to create what’s called a “main” component, which is the one that you’ll update as needed going forward. Other components — the ones that you’ll actually insert into your designs — will be copies (or “instances”) of the main component, which is sort of the point, right? Update once, and the changes reflect everywhere.

Here’s one I made earlier, minus the colors:

To apply a design token, make sure that you’re on the “Tokens” tab and have the relevant layer selected, then select the design token that you want to apply to it:

It doesn’t matter which variant you create first, but you’ll probably want to go with the default one as a starting point, as I’ve done. Either way, to turn this button into a main component, select the button object via the canvas (or “Layers” tab), right-click on it, then choose the “Create component” option from the context menu (or just press Ctrl / ⌘ + K after selecting it).

Remember to name the component as well. You can do that by double-clicking on the name (also via the canvas or “Layers” tab).

Step 3: Create The Component Variants

To create a variant, select the main component and either hit the Ctrl / ⌘ + K keyboard shortcut, or click on the icon that reveals the “Create variant” tooltip (located in the “Design” tab in the right panel).

Next, while the variant is still selected, make the necessary design changes via the “Design” tab. Or, if you want to swap design tokens out for other design tokens, you can do that in the same way that you applied them to begin with, via the “Tokens” tab. Rinse and repeat until you have all of your variants on the canvas designed:

After that, as you might’ve guessed, you’ll want to name your variants. But avoid doing this via the “Layers” panel. Instead, select a variant and replace “Property 1” with a label that describes the differentiating property of each variant. Since my button variants in this example represent different states of the same button, I’ve named this “State”. This applies to all of the variants, so you only need to do this once.

Next to the property name, you’ll see “Value 1” or something similar. Edit that for each variant, for example, the name of the state. In my case, I’ve named them “Default”, “Hover”, and “Disabled”.

And yes, you can add more properties to a component. To do this, click on the nearby plus (+) icon. I’ll talk more about component variants at scale in a minute, though.

To see the component in action, switch to the “Assets” tab (located in the left panel) and drag the component onto the canvas to initialize one instance of it. Again, remember to choose the correct property value from the “Design” tab:

If you already have a Penpot design system, combining multiple components into one component with variants is not only easy and error-proof, but you might be good to go already if you’re using a robust property naming system that uses forward slashes (/). Penpot has put together a very straightforward guide, but the diagram below sums it up pretty well:

How Component Variants Work At Scale

Design tokens, components, and component variants — the triple-threat of design systems — work together, not just to create powerful yet flexible design systems, but sustainable design systems that scale. This is easier to accomplish when thinking ahead, starting with design tokens that separate the “what” from the “what for” using token aliases, despite how verbose that might seem at first.

For example, I used color.brand.lightest for the text color of every variant, but instead of plugging that color token in directly, I created aliases such as text.button.primary.default. This means that I can change the text color of any variant later without having to dive into the actual variant on the canvas, or force a change to color.brand.lightest that might impact a bunch of other components.

Because remember, while the component and its variants give us reusability of the button, the color tokens give us reusability of the colors, which might be used in dozens, if not hundreds, of other components. A design system is like a living, breathing ecosystem, where some parts of it are connected, some parts of it aren’t connected, and some parts of it are or aren’t connected but might have to be later, and we need to be ready for that.

The good news is that Penpot makes all of this pretty easy to manage as long as you do a little planning beforehand.

Consider the following:

• The design tokens that you’ll reuse (e.g., colors, font sizes, and so on),
• Where design token aliases will be reused (e.g., buttons, headings, and so on),
• Organizing the design tokens into sets,
• Organizing the sets into themes,
• Organizing the themes into groups,
• The different components that you’ll need, and
• The different variants and variant properties that you’ll need for each component.

Even the buttons that I designed here today can be scaled far beyond what I’ve already mocked up. Think of all the possible variants that might come up, such as a secondary button color, a tertiary color, a confirmation color, a warning color, a cancelled color, different colors for light and dark mode, not to mention more properties for more states, such as active and focus states. What if we want a whole matrix of variants, like where buttons in a disabled state can be hovered and where all buttons can be focused upon? Or where some buttons have icons instead of text labels, or both?

Designs can get very complicated, but once you’ve organized them into design tokens, components, and component variants in Penpot, they’ll actually feel quite simple, especially once you’re able to see them on the canvas, and even more so once you’ve made a significant change in just a few seconds without breaking anything.

Conclusion

This is how we make component variants work at scale. We get the benefits of reusability while keeping the flexibility to fork any aspect of our design system, big or small, without breaking out of it. And design tools like Penpot make it possible to not only establish a design system, but also express its design tokens and styles as code.

(gg, yk)

This article is sponsored by Penpot

It’s already the fifth time I’m writing to you about Penpot — and what a journey it continues to be! During this time, Penpot’s presence in the design tools scene has grown strong. In a market that recently felt more turbulent than ever, I’ve always appreciated Penpot for their clear mission and values. They’ve built a design tool that not only delivers great features but is also open-source and developed in active dialogue with the community. Rather than relying on closed formats and gated solutions, Penpot embraces open web standards and commonly used technologies — ensuring it works seamlessly across platforms and integrates naturally with code.

Their latest release is another great example of that approach. It’s also one of the most impactful. Let me introduce you to design tokens in Penpot.

Design tokens are an essential building block of modern user interface design and engineering. But so far, designers and engineers have been stuck with third-party plugins and cumbersome APIs to collaborate effectively on design tokens and keep them in sync. It’s high time we had tools and processes that handle this better, and Penpot just made it happen.

About Design Tokens

Design tokens can be understood as a framework to document and organize your design decisions. They act as a single source of truth for both designers and engineers and include all the design variables, such as colors, typography, spacing, fills, borders, and shadows.

The concept of design tokens has grown in popularity alongside the rise of design systems and the increasing demand for broader standards and guidelines in user interface design. Design tokens emerged as a solution for managing increasingly complex systems while keeping them structured, scalable, and extensible.

The goal of using design tokens is not only to make design decisions more intentional and maintainable but also to make it easier to keep them in sync with code. In the case of larger systems, it is often a one-to-many relationship. Design tokens allow you to keep the values agnostic of their application and scale them across various products and environments.

Design tokens create a semantic layer between the values, the tools used to define them, and the software that implements them.

“

On top of maintainability benefits, a common reason to use design tokens is theming. Keeping your design decisions decoupled means that you can easily swap the values across multiple sets. This allows you to change the appearance of the entire interface with applications ranging from simple light and dark mode implementations to more advanced use cases, such as handling multiple brands or creating fully customizable and adjustable UIs.

Implementation Challenges

Until recently, there was no standardized format for maintaining design tokens — it remained a largely theoretical concept, implemented differently across teams and tools. Every design tool or frontend framework has its own approach. Syncing code with design tools was also a major pain point, often requiring third-party plugins and unreliable synchronization solutions.

However, in recent years, W3C, the international organization responsible for developing open standards and protocols for the web, brought to life a dedicated Design Tokens Community Group with the goal of creating an open standard for products and design tools to handle design tokens. Once this standard gets more widely adopted, it will give us hope for a more predictable and standardized approach to design tokens across the industry.

To make that happen, work has to be done on two ends, both design and development. Penpot is the very first design tool to implement design tokens in adherence to the standard that the W3C is working on. It also solves the problem of third-party dependencies by offering a native API with all the values served in the official, standardized format.

Design Tokens In Practice

To better understand design tokens and how to use them in practice, let’s take a look at an example together. Let’s consider the following user interface of a login screen:

Imagine we want this design to work in light and dark mode, but also to be themable with several accent colors. It could be that we’re using the same authentication system for websites of several associated brands or several products. We could also want to allow the user to customize the interface to their needs.

If we want to build a design that works for three accent colors, each with light and dark themes, it gives us six variants in total:

Designing all of them by hand would not only be tedious but also difficult to maintain. Every change you make would have to be repeated in six places. In the case of six variants, that’s not ideal, but it’s still doable. But what if you also want to support multiple layout options or more brands? It could easily scale into hundreds of combinations, at which point designing them manually would easily get out of hand.

This is where design tokens come to the rescue. They allow you to effectively maintain all the variants and test all the possible combinations, even hundreds of them, while still building a single design without repetitive work.

You can start by creating a design in one of the variants before starting to think about the tokens. Having a design already in place might make it easier to plan your tokens’ hierarchy and structure accordingly.

In this case, I created three components: 2 types of buttons and input, and combined them with text layers into several Flex layouts to build out this screen. If you’d like to first learn more about building components and layouts in Penpot, I would recommend you revisit some of my previous articles:

• Build Design Systems With Penpot Components
• Penpot’s CSS Grid Layout: Designing With Superpowers
• Penpot’s Flex Layout: Building CSS Layouts In A Design Tool

Now that we have the design ready, we can start creating tokens. You can create your first token by heading to the tokens tab of the left sidebar and clicking the plus button in one of the token categories. Let’s start by creating a color.

To use design tokens effectively, it’s critical to plan their naming and structure well. You might have noticed that when I created a token, Penpot automatically created for me a new set, called Global. All design tokens have to be organized within sets.

I called my first set “primitives,” so I can store literal values such as “blue,” “purple,” or “grey.” To support multiple shades of color, I used numbers, so the final token names I used are, for example, “slate.1” or “slate.10”.

At this point, we can start thinking about handling multiple colors for various themes. To make it easy to switch between tokens, all you have to do is create multiple sets with tokens of the same names. To do that, I split the primitives into two sets, “light” and “dark.” You can nest your token sets by adding slashes into their names.

In the video above, you can see that I have two sets, light and dark, each with tokens of the same names but different values. At this point, you could already reference your primitive tokens to switch between light and dark values. However, in the future, you might use the same shade of grey for multiple purposes, like border, background, or text. It would be a more maintainable approach to keep these definitions independent.

To achieve that, we need to introduce a second abstraction layer. In this case, I created a new tokens set called “globals” that references the primitives set. All values in “globals” reference other already existing tokens, such as “primitives.”

For globals, I used semantic naming such as “text.muted” or “background.primary” to stress that the token names are agnostic from their literal values. In other words, the “text.muted” name works well for both light and dark modes, the same as “background.primary” works as a token name no matter what brand color is currently in use. For comparison, “text.dark” or “background.blue” would not make sense if we wanted to make them dynamic and be able to switch between different modes and brand colors.

In Penpot, you can reference other tokens in token values by wrapping them in curly brackets. So, if you select “slate.1” as your text color, it will reference the “slate.1” value from any other set that is currently active. With the light set active, the text will be black. And with the dark set active, the text will be white.

You can apply your global tokens to any layer you want. To do that, select a layer and then right-click a token of your choice. In the context menu, you can select among the values that are compatible with a token. In the case of a color, it will be either fill or stroke.

Now, if you switch on and off the sets, you can see the design responding to the change. With the light set active, the text appears black, and with the dark set active, the text appears white.

As you probably noticed, more than one set can be active at the same time, even if they contain values of the same names, like light and dark sets. In such a case, a set lowest on the list will override the already defined values. You can think of it as defining variables in any programming language or properties in CSS. The last value of equal specificity is the one that counts.

However, you don’t need to switch the sets on and off manually to test your design’s appearance. To make that easier, Penpot also offers another concept called Themes. Themes are the best way to manage your sets and combine them into functional design choices.

In the case of light and dark mode, I created two themes: “light” and “dark,” under a group called “Mode.” This makes it much clearer how the sets should be used and makes it easier to switch between the predefined options.

For each theme, I selected two sets. One that defines the values (“light” or “dark”) and one that is actually used to style the designs (“globals”). Now, you can use the Themes dropdown to quickly switch themes.

At this point, we have two layers of abstraction: primitives (such as basic color shades) and a semantic layer (background, text, and so on). Sometimes, you might need more than that. With this setup, you can easily switch between light and dark mode, but what if you also want to switch between the several brand colors I showed earlier, while still being able to change the mode? For that, we need another theme (let’s call it “Brand”) and another couple of sets under a parent set that would also be called “Brand.” For the latter, I made three options: “Slate,” “Indigo,” and “Purple.” In real-life scenarios, these could be names of brands, products, and so on.

To bring it all together, the brand sets need to reference primitives, while the “globals” set needs to reference “brand” sets. This way, we are creating three different brands, each with its own separate values for light and dark mode.

This allows us to switch between brands and modes and test all the possible combinations.

What’s Next?

I hope you enjoyed following this example. If you’d like to check out the file presented above before creating your own, you can duplicate it here.

Colors are only one of many types of tokens available in Penpot. You can also use design tokens to maintain values such as spacing, sizing, layout, and so on. The Penpot team is working on gradually expanding the choice of tokens you can use. All are in accordance with the upcoming design tokens standard.

The benefits of the native approach to design tokens implemented by Penpot go beyond ease of use and standardization. It also makes the tokens more powerful. For example, they already support math operations using the calc() function you might recognize from CSS. It means you can use math to add, multiply, subtract, etc., token values.

Once you have the design token in Penpot ready, the next step is to bring it over to your code. Already today, you can export the tokens in JSON format, and soon, an API will be available that connects and imports the tokens directly into your codebase. You can follow Penpot on LinkedIn, BlueSky, and other social media to be the first to hear about the next updates. The team behind Penpot is also planning to make its design tokens implementation even more powerful in the near future with support for gradients, composite tokens (tokens that store multiple values), and more.

To learn more about design tokens and how to use them, check out the following links:

• Design Token Overview, Penpot website
• What are design tokens? A complete guide, Penpot Blog
• Design Tokens, Penpot Docs
• Design tokens format module, W3C Community Group Draft Report

Conclusion

By adding support for native design tokens, Penpot is making real progress on connecting design and code in meaningful ways. Having all your design variables well documented and organized is one thing. Doing that in a scalable and maintainable way that is based on open standards and is easy to connect with code &mdahs; that’s yet another level.

The practical benefits are huge: better maintainability, less friction, and easier communication across the whole team. If you’re looking to bring more structure to your design system while keeping designers and engineers in sync, Penpot’s design tokens implementation is definitely worth exploring.

Tried it already? Share your thoughts! The Penpot team is active on social media, or just share your feedback in the comments section below.

(yk)

I recently wrote for Smashing Magazine about how UX leaders face increasing pressure to deliver more with limited resources. Let me show you how a digital playbook can help meet this challenge by enhancing our work’s visibility while boosting efficiency.

While a design system ensures visual coherence, a digital playbook lays out the strategic and operational framework for how digital projects should be executed and managed. Here’s why a digital playbook deserves a place in your organization’s toolbox and what it should include to drive meaningful impact.

What Is A Digital Playbook?

A digital playbook is essentially your organization’s handbook for navigating the complexities of digital work. As a user experience consultant, I often help organizations create tools like this to streamline their processes and improve outcomes. It’s a collection of strategies, principles, and processes that provide clarity on how to handle everything from website creation to content management and beyond. Think of it as a how-to guide for all things digital.

Unlike rigid rulebooks that feel constraining, you’ll find that a playbook evolves with your organization’s unique culture and challenges. You can use it to help stakeholders learn, standardize your work, and help everybody be more effective. Let me show you how a playbook can transform the way your team works.

Why You Need A Digital Playbook

Have you ever faced challenges like these?

• Stakeholders with conflicting expectations of what the digital team should deliver.
• Endless debates over project priorities and workflows that stall progress.
• A patchwork of tools and inconsistent policies that create confusion.
• Uncertainty about best practices, leading to inefficiencies and missed opportunities.

Let me show you how a playbook can help you and your team in four key ways:

• It helps you educate your stakeholders by making digital processes transparent and building trust. I’ve found that when you explain best practices clearly, everyone gets on the same page quickly.
• You’ll streamline your processes with clear, standardized workflows. This means less confusion and faster progress on your projects.
• Your digital team gains more credibility as you step into a leadership role. You’ll be able to show your real value to the organization.
• Best of all, you’ll reduce friction in your daily work. When everyone understands the policies, you’ll face fewer misunderstandings and conflicts.

A digital playbook isn’t just a tool; it’s a way to transform challenges into opportunities for greater impact.

“

But, no doubt you are wondering, what exactly goes into a digital playbook?

Key Components Of A Digital Playbook

Every digital playbook is unique, but if you’ve ever wondered where to start, here are some key areas to consider. Let’s walk through them together.

Engaging With The Digital Team

Have you ever had people come to you too late in the process or approach you with solutions rather than explaining the underlying problems? A playbook can help mitigate these issues by providing clear guidance on:

• How to request a new website or content update at the right time;
• What information you require to do your job;
• What stakeholders need to consider before requesting your help.

By addressing these common challenges, you’re not just reducing your frustrations — you’re educating stakeholders and encouraging better collaboration.

Digital Project Lifecycle

Most digital projects can feel overwhelming without a clear structure, especially for stakeholders who may not understand the intricacies of the process. That’s why it’s essential to communicate the key phases clearly to those requesting your team’s help. For example:

• Discovery: Explain how your team will research goals, user needs, and requirements to ensure the project starts on solid ground.
• Prototyping: Highlight the importance of testing initial concepts to validate ideas before full development.
• Build: Detail the process of developing the final product and incorporating feedback.
• Launch: Set clear expectations for rolling out the project with a structured plan.
• Management: Clarify how the team will optimize and maintain the product over time.
• Retirement: Help stakeholders understand when and how to phase out outdated tools or content effectively.

I’ve structured the lifecycle this way to help stakeholders understand what to expect. When they know what’s happening at each stage, it builds trust and helps the working relationship. Stakeholders will see exactly what role you play and how your team adds value throughout the process.

Publishing Best Practices

Writing for the web isn’t the same as traditional writing, and it’s critical for your team to help stakeholders understand the differences. Your playbook can include practical advice to guide them, such as:

• Planning and organizing content to align with user needs and business goals.
• Crafting content that’s user-friendly, SEO-optimized, and designed for clarity.
• Maintaining accessible and high-quality standards to ensure inclusivity.

By providing this guidance, you empower stakeholders to create content that’s not only effective but also reflects your team’s standards.

Understanding Your Users

Helping stakeholders understand your audience is essential for creating user-centered experiences. Your digital playbook can support this by including:

• Detailed user personas that highlight specific needs and behaviors.
• Recommendations for tools and methods to gather and analyze user data.
• Practical tips for ensuring digital experiences are inclusive and accessible to all.

By sharing this knowledge, your team helps stakeholders make decisions that prioritize users, ultimately leading to more successful outcomes.

Recommended Resources

Stakeholders often are unaware of the wealth of resources that can help them improve their digital deliverables. Your playbook can help by recommending trusted solutions, such as:

• Tools that enable stakeholders to carry out their own user research and testing.
• Analytics tools that allow stakeholders to track the performance of their websites.
• A list of preferred suppliers in case stakeholders need to bring in external experts.

These recommendations ensure stakeholders are equipped with reliable resources that align with your team’s processes.

Policies And Governance

Uncertainty about organizational policies can lead to confusion and missteps. Your playbook should provide clarity by outlining:

• Accessibility and inclusivity standards to ensure compliance and user satisfaction.
• Data privacy and security protocols to safeguard user information.
• Clear processes for prioritizing and governing projects to maintain focus and consistency.

By setting these expectations, your team establishes a foundation of trust and accountability that stakeholders can rely on.

Of course, you can have the best digital playbook in the world, but if people don’t reference it, then it is a wasted opportunity.

Making Your Digital Playbook Stick

It falls to you and your team to ensure as many stakeholders as possible engage with your playbook. Try the following:

• Make It Easy to Find
  How often do stakeholders struggle to find important resources? Avoid hosting the playbook in a forgotten corner of your intranet. Instead, place it front and center on a well-maintained, user-friendly site that’s accessible to everyone.
• Keep It Engaging
  Let’s face it — nobody wants to sift through walls of text. Use visuals like infographics, short explainer videos, and clear headings to make your playbook not only digestible but also enjoyable to use. Think of it as creating a resource your stakeholders will actually want to refer back to.
• Frame It as a Resource
  A common pitfall is presenting the playbook as a rigid set of rules. Instead, position it as a helpful guide designed to make everyone’s work easier. Highlight how it can simplify workflows, improve outcomes, and solve real-world problems your stakeholders face daily.
• Share at Relevant Moments
  Don’t wait for stakeholders to find the playbook themselves. Instead, proactively share relevant sections when they’re most needed. For example, send the discovery phase documentation when starting a new project or share content guidelines when someone is preparing to write for the website. This just-in-time approach ensures the playbook’s guidance is applied when it matters most.

Start Small, Then Scale

Creating a digital playbook might sound like a daunting task, but it doesn’t have to be. Begin with a few core sections and expand over time. Assign ownership to a specific team or individual to ensure it remains updated and relevant.

In the end, a digital playbook is an investment. It saves time, reduces conflicts, and elevates your organization’s digital maturity.

Just as a design system is critical for visual harmony, a digital playbook is essential for operational excellence.

“

Further Reading On SmashingMag

• “Design Patterns Are A Better Way To Collaborate On Your Design System,” Ben Clemens
• “Design Systems: Useful Examples and Resources,” Cosima Mielke
• “Building Components For Consumption, Not Complexity (Part 1),” Luis Ouriach
• “Taking The Stress Out Of Design System Management,” Masha Shaposhnikova

(yk)

This article is sponsored by Storyblok

Open source is the backbone of modern software development. As someone deeply involved in both community-driven and company-driven open source, I’ve had the privilege of experiencing its diverse approaches firsthand. This article dives into what modern OSS (Open Source) authoring looks like, focusing on front-end JavaScript libraries such as TresJS and tools I’ve contributed to at Storyblok.

But let me be clear:

There’s no universal playbook for OSS. Every language, framework, and project has its own workflows, rules, and culture — and that’s okay. These variations are what make open source so adaptable and diverse.

The Art Of OSS Authoring

Authoring an open-source project often begins with scratching your own itch — solving a problem you face as a developer. But as your “experiment” gains traction, the challenge shifts to addressing diverse use cases while maintaining the simplicity and focus of the original idea.

Take TresJS as an example. All I wanted was to add 3D to my personal Nuxt portfolio, but at that time, there wasn’t a maintained, feature-rich alternative to React Three Fiber in VueJS. So, I decided to create one. Funny enough, after two years after the library’s launch, my portfolio remains unfinished.

Community-driven OSS Authoring: Lessons From TresJS

Continuing with TresJS as an example of a community-driven OSS project, the community has been an integral part of its growth, offering ideas, filing issues (around 531 in total), and submitting pull requests (around 936 PRs) of which 90% eventually made it to production. As an author, this is the best thing that can happen — it’s probably one of the biggest reasons I fell in love with open source. The continuous collaboration creates an environment where new ideas can evolve into meaningful contributions.

However, it also comes with its own challenges. The more ideas come in, the harder it becomes to maintain the project’s focus on its original purpose.

As authors, it’s our responsibility to keep the vision of the library clear — even if that means saying no to great ideas from the community.

Over time, some of the most consistent collaborators became part of a core team, helping to share the responsibility of maintaining the library and ensuring it stays aligned with its original goals.

Another crucial aspect of scaling a project, especially one like TresJS, which has grown into an ecosystem of packages, is the ability to delegate. The more the project expands, the more essential it becomes to distribute responsibilities among contributors. Delegation helps in reducing the burden of the massive workload and empowers contributors to take ownership of specific areas. As a core author, it’s equally important to provide the necessary tools, CI workflows, and clear conventions to make the process of contributing as simple and efficient as possible. A well-prepared foundation ensures that new and existing collaborators can focus on what truly matters — pushing the project forward.

Company-driven OSS Authoring: The Storyblok Perspective

Now that we’ve explored the bright spots and challenges of community-driven OSS let’s jump into a different realm: company-driven OSS.

I had experience with inner-source and open-source in previous companies, so I already had a grasp of how OSS works in the context of a company environment. However, my most meaningful experience would come later, specifically earlier this year, when I switched my role from DevRel to a full-time Developer Experience Engineer, and I say “full-time” because before taking the role, I was already contributing to Storyblok’s SDK ecosystem.

At Storyblok, open source plays a crucial role in how we engage with developers and how they seamlessly use our product with their favorite framework. Our goal is to provide the same developer experience regardless of the flavor, making the experience of using Storyblok as simple, effective, and enjoyable as possible.

To achieve this, it’s crucial to balance the needs of the developer community — which often reflect the needs of the clients they work for — with the company’s broader goals. One of the things I find more challenging is managing expectations. For instance, while the community may want feature requests and bug fixes to be implemented quickly, the company’s priorities might dictate focusing on stability, scalability, and often strategic integrations. Clear communication and prioritization are key to maintaining healthy alignment and trust between both sides.

One of the unique advantages of company-driven open source is the availability of resources:

• Dedicated engineering time,
• Infrastructure (which many OSS authors often cannot afford),
• Access to knowledge from internal teams like design, QA, and product management.

However, this setup often comes with the challenge of dealing with legacy codebases — typically written by developers who may not be familiar with OSS principles. This can lead to inconsistencies in structure, testing, and documentation that require significant refactoring before the project can align with open-source best practices.

Navigating The Spectrum: Community vs. Company

I like to think of community-driven OSS as being like jazz music—freeform, improvised, and deeply collaborative. In contrast, company-driven OSS resembles an orchestra, with a conductor guiding the performance and ensuring all the pieces fit together seamlessly.

The truth is that most OSS projects — if not the vast majority — exist somewhere along this spectrum. For example, TresJS began as a purely community-driven project, but as it matured and gained traction, elements of structured decision-making — more typical of company-driven projects — became necessary to maintain focus and scalability. Together with the core team, we defined a vision and goals for the project to ensure it continued to grow without losing sight of its original purpose.

Interestingly, the reverse is also true: Company-driven OSS can benefit significantly from the fast-paced innovation seen in community-driven projects.

Many of the improvements I’ve introduced to the Storyblok ecosystem since joining were inspired by ideas first explored in TresJS. For instance, migrating the TresJS ecosystem to pnpm workspaces demonstrated how streamlined dependency management could improve development workflows like playgrounds and e2e — an approach we gradually adapted later for Storyblok’s ecosystem.

Similarly, transitioning Storyblok testing from Jest to Vitest, with its improved performance and developer experience, was influenced by how testing is approached in community-driven projects. Likewise, our switch from Prettier to ESLint’s v9 flat configuration with auto-fix helped consolidate linting and formatting into a single workflow, streamlining developer productivity.

Even more granular processes, such as modernizing CI workflows, found their way into Storyblok. TresJS’s evolution from a single monolithic release action to granular steps for linting, testing, and building provided a blueprint for enhancing our pipelines at Storyblok. We also adopted continuous release practices inspired by pkg.pr.new, enabling faster delivery of incremental changes and testing package releases in real client projects to gather immediate feedback before merging the PRs.

That said, TresJS also benefited from my experiences at Storyblok, which had a more mature and battle-tested ecosystem, particularly in adopting automated processes. For example, we integrated Dependabot to keep dependencies up to date and used auto-merge to reduce manual intervention for minor updates, freeing up contributors’ time for more meaningful work. We also implemented an automatic release pipeline using GitHub Actions, inspired by Storyblok’s workflows, ensuring smoother and more reliable releases for the TresJS ecosystem.

The Challenges of Modern OSS Authoring

Throughout this article, we’ve touched on several modern OSS challenges, but if one deserves the crown, it’s managing breaking changes and maintaining compatibility. We know how fast the pace of technology is, especially on the web, and users expect libraries and tools to keep up with the latest trends. I’m not the first person to say that hype-driven development can be fun, but it is inherently risky and not your best ally when building reliable, high-performance software — especially in enterprise contexts.

Breaking changes exist. That’s why semantic versioning comes into play to make our lives easier. However, it is equally important to balance innovation with stability. This becomes more crucial when introducing new features or refactoring for better performance, breaking existing APIs. One key lesson I’ve learned — particularly during my time at Storyblok — is the importance of clear communication. Changelogs, migration guides, and deprecation warnings are invaluable tools to smoothen the transition for users.

A practical example:

My first project as a Developer Experience Engineer was introducing @storyblok/richtext, a library for rich-text processing that (at the time of writing) sees around 172k downloads per month. The library was crafted during my time as a DevRel, but transitioning users to it from the previous rich-text implementation across the ecosystem required careful planning. Since the library would become a dependency of the fundamental JS SDK — and from there propagate to all the framework SDKs — together with my manager, we planned a multi-month transition with a retro-compatible period before the major release. This included communication campaigns, thorough documentation, and gradual adoption to minimize disruption.

Despite these efforts, mistakes happened — and that’s okay. During the rich-text transition, there were instances where updates didn’t arrive on time or where communication and documentation were temporarily out of sync. This led to confusion within the community, which we addressed by providing timely support on GitHub issues and Discord. These moments served as reminders that even with semantic versioning, modular architectures, and meticulous planning, OSS authoring is never perfect. Mistakes are part of the process.

And that takes us to the following point.

Conclusion

Open-source authoring is a journey of continuous learning. Each misstep offers a chance to improve, and each success reinforces the value of collaboration and experimentation.

There’s no “perfect” way to do OSS, and that’s the beauty of it. Every project has its own set of workflows, challenges, and quirks shaped by the community and its contributors. These differences make open source adaptable, dynamic, fun, and, above all, impactful. No matter if you’re building something entirely new or contributing to an existing project, remember that progress, not perfection, is the goal.

So, keep contributing, experimenting, and sharing your work. Every pull request, issue, and idea you put forward brings value &mdashp not just to your project but to the broader ecosystem.

Happy coding!

(yk)

The groundwork for what we call today “signals” dates as early as the 1970s. Based on this work, they became popular with different fields of computer science, defining them more specifically around the 90s and the early 2000s.

In Web Development, they first made a run for it with KnockoutJS, and shortly after, signals took a backseat in (most of) our brains. Some years ago, multiple similar implementations came to be.

• MobX observable states
• Vue.js refs and shallow refs
• SolidJS signals

With different names and implementation details, those approaches are similar enough to be wrapped in a category we know today as Fine-Grained Reactivity, even if they have different levels of “fine” x “coarse” updates — we’ll get more into what this means soon enough.

To summarize the history: Even being an older technology, signals started a revolution in how we thought about interactivity and data in our UIs at the time. And since then, every UI library (SolidJS, Marko, Vue.js, Qwik, Angular, Svelte, Wiz, Preact, etc) has adopted some kind of implementation of them (except for React).

Typically, a signal is composed of an accessor (getter) and a setter. The setter establishes an update to the value held by the signal and triggers all dependent effects. While an accessor pulls the value from the source and is run by effects every time a change happens upstream.

const [signal, setSignal] = createSignal("initial value");

setSignal("new value");

console.log(signal()); // "new value"

In order to understand the reason for that, we need to dig a little deeper into what API Architectures and Fine-Grained Reactivity actually mean.

API Architectures

There are two basic ways of defining systems based on how they handle their data. Each of these approaches has its pros and cons.

• Pull: The consumer pings the source for updates.
• Push: The source sends the updates as soon as they are available.

Pull systems need to handle polling or some other way of maintaining their data up-to-date. They also need to guarantee that all consumers of the data get torn down and recreated once new data arrives to avoid state tearing.

State Tearing occurs when different parts of the same UI are at different stages of the state. For example, when your header shows 8 posts available, but the list has 10.

Push systems don’t need to worry about maintaining their data up-to-date. Nevertheless, the source is unaware of whether the consumer is ready to receive the updates. This can cause backpressure. A data source may send too many updates in a shorter amount of time than the consumer is capable of handling. If the update flux is too intense for the receiver, it can cause loss of data packages (leading to state tearing once again) and, in more serious cases, even crash the client.

In pull systems, the accepted tradeoff is that data is unaware of where it’s being used; this causes the receiving end to create precautions around maintaining all their components up-to-date. That’s how systems like React work with their teardown/re-render mechanism around updates and reconciliation.

In push systems, the accepted tradeoff is that the receiving end needs to be able to deal with the update stream in a way that won’t cause it to crash while maintaining all consuming nodes in a synchronized state. In web development, RxJS is the most popular example of a push system.

The attentive reader may have noticed the tradeoffs on each system are at the opposite ends of the spectrum: while pull systems are good at scheduling the updates efficiently, in push architectures, the data knows where it’s being used — allows for more granular control. That’s what makes a great opportunity for a hybrid model.

Push-Pull Architectures

In Push-Pull systems, the state has a list of subscribers, which can then trigger for re-fetching data once there is an update. The way it differs from traditional push is that the update itself isn’t sent to the subscribers — just a notification that they’re now stale.

Once the subscriber is aware its current state has become stale, it will then fetch the new data at a proper time, avoiding any kind of backpressure and behaving similarly to the pull mechanism. The difference is that this only happens when the subscriber is certain there is new data to be fetched.

We call these data signals, and the way those subscribers are triggered to update are called effects. Not to confuse with useEffect, which is a similar name for a completely different thing.

Fine-Grained Reactivity

Once we establish the two-way interaction between the data source and data consumer, we will have a reactive system.

A reactive system only exists when data can notify the consumer it has changed, and the consumer can apply those changes.

Now, to make it fine-grained there are two fundamental requirements that need to be met:

1. Efficiency: The system only executes the minimum amount of computations necessary.
2. Glitch-Free: No intermediary states are shown in the process of updating a state.

Efficiency In UIs

To really understand how signals can achieve high levels of efficiency, one needs to understand what it means to have an accessor. In broad strokes, they behave as getter functions. Having an accessor means the value does not exist within the boundaries of our component — what our templates receive is a getter for that value, and every time their effects run, they will bring an up-to-date new value. This is why signals are functions and not simple variables. For example, in Solid:

import { createSignal } from 'solid-js'

function ReactiveComponent() {
  const [signal, setSignal] = createSignal()
  
  return (
    <h1>Hello, {signal()}</h1>
  )
}

The part that is relevant to performance (and efficiency) in the snippet above is that considering signal() is a getter, it does not need to re-run the whole ReactiveComponent() function to update the rendered artifact; only the signal is re-run, guaranteeing no extra computation will run.

Glitch-Free UIs

Non-reactive systems avoid intermediary states by having a teardown/re-render mechanism. They toss away the artifacts with possibly stale data and recreate everything from scratch. That works well and consistently but at the expense of efficiency.

In order to understand how reactive systems handle this problem, we need to talk about the Diamond Challenge. This is a quick problem to describe but a tough one to solve. Take a look at the diagram below:

Pay attention to the E node. It depends on D and B, but only D depends on C.

If your reactive system is too eager to update, it can receive the update from B while D is still stale. That will cause E to show an intermediary state that should not exist.

It’s easy and intuitive to have A trigger its children for updates as soon as new data arrives and let it cascade down. But if this happens, E receives the data from B while D is stale. If B is able to trigger an update from E, E will show an intermediate state.

Each implementation adopts different update strategies to solve this challenge. They can be grouped into two categories:

1. Lazy Signals
   Where a scheduler defines the order within which the updates will occur. (A, then B and C, then D, and finally E).
2. Eager Signals
   When signals are aware if their parents are stale, checking, or clean. In this approach, when E receives the update from B, it will trigger a check/update on D, which will climb up until it can ensure to be back in a clean state, allowing E to finally update.

Back To Our UIs

After this dive into what fine-grained reactivity means, it’s time to take a step back and look at our websites and apps. Let’s analyze what it means to our daily work.

DX And UX

When the code we wrote is easier to reason about, we can then focus on the things that really matter: the features we deliver to our users. Naturally, tools that require less work to operate will deliver less maintenance and overhead for the craftsperson.

A system that is glitch-free and efficient by default will get out of the developer’s way when it’s time to build with it. It will also enforce a higher connection to the platform via a thinner abstraction layer.

When it comes to Developer Experience, there is also something to be said about known territory. People are more productive within the mental models and paradigms they are used to. Naturally, solutions that have been around for longer and have solved a larger quantity of challenges are easier to work with, but that is at odds with innovation. It was a cognitive exercise when JSX came around and replaced imperative DOM updates with jQuery. In the same way, a new paradigm to handle rendering will cause a similar discomfort until it becomes common.

Going Deeper

We will talk further about this in the next article, where we’re looking more closely into different implementations of signals (lazy, eager, hybrid), scheduled updates, interacting with the DOM, and debugging your own code!

Meanwhile, you can find me in the comments section below, on 𝕏 (Twitter), LinkedIn, BlueSky, or even youtube. I’m always happy to chat, and if you tell me what you want to know, I’ll make sure to include it in the next article! See ya!

(yk)

This article is sponsored by Penpot

Penpot is a free, open-source design tool that allows true collaboration between designers and developers. Designers can create interactive prototypes and design systems at scale, while developers enjoy ready-to-use code and make their workflow easy and fast because it’s built with web technologies, works in the browser, and has already passed 33K starts on GitHub.

The UI feels intuitive and makes it easy to get things done, even for someone who’s not a designer (guilty as charged!). You can get things done in the same way and with the same quality as with other more popular and closed-source tools like Figma.

Why Open-Source Is Important

As someone who works with commercial open-source on my day-to-day, I strongly believe in it as a way to be closer to your users and unlock the next level of delivery. Being open-source creates a whole new level of accountability and flexibility for a tool.

Developers are a different breed of user. When we hit a quirk or a gap in the UX, our first instinct is to play detective and figure out why that pattern stuck out as a sore thumb to what we’ve been doing. When the code is open-source, it’s not unusual for us to jump into the source and create an issue with a proposal on how to solve it already. At least, that’s the dream.

On top of that, being open-source allows you and your team to self-host, giving you that extra layer of privacy and control, or at least a more cost-effective solution if you have the time and skills to DYI it all.

When the cards are played right, and the team is able to afford the long-term benefits, commercial open-source is a win-win strategy.

Introducing: Penpot Plugin System

Talking about the extensibility of open-source, Penpot has the PenpotHub the home for open-source templates and the newly released plugin gallery. So now, if there’s a functionality missing, you don’t need to jump into the code-base straightaway — you can create a plugin to achieve what you need. And you can even serve it from localhost!

Creating Penpot Plugins

When it comes to the plugins, creating one is extremely ergonomic. First, there are already set templates for a few frameworks, and I created one for SolidJS in this PR — the power of open-source!

When using Vite, plugins are Single-Page Applications; if you have ever built a Hello World app with Vite, you have what it takes to create a plugin. On top of that, the Penpot team has a few packages that can give you a headstart in the process:

npm install @penpot/plugin-styles

That will allow you to import with a CSS loader or a CSS import from @penpot/plugin-styles/styles.css. The JavaScript API is available through the window object, but if your plugin is in TypeScript, you need to teach it:

npm add -D @penpot/plugin-types

With those types in your node_modules, you can pop-up the tsconfig.json and add the types to the compilerOptions.

{
  "compilerOptions": {
    "types": ["@penpot/plugin-types"]
  }
}

And there you are, now, the Language Service Provider in your editor and the TypeScript Compiler will accept that penpot is a valid namespace, and you’ll have auto-completion for the Penpot APIs throughout your entire project. For example, defining your plugin will look like the following:

penpot.ui.open("Your Plugin Name", "", {
  width: 500,
  height: 600
})

The last step is to define a plugin manifest in a manifest.json file and make sure it’s in the outpot directory from Vite. The manifest will indicate where each asset is and what permissions your plugin requires to work:

{
  "name": "Your Plugin Name",
  "description": "A Super plugin that will win Penpot Plugin Contest",
  "code": "/plugin.js",
  "icon": "/icon.png",
  "permissions": [
    "content:read",
    "content:write",
    "library:read",
    "library:write",
    "user:read",
    "comment:read",
    "comment:write",
    "allow:downloads"
  ]
}

Once the initial setup is done, the communication between the Penpot API and the plugin interface is done with a bidirectional messaging system, not so different than what you’d do with a Web-Worker.

So, to send a message from your plugin to the Penpot API, you can do the following:

penpot.ui.sendMessage("Hello from my Plugin");

And to receive it back, you need to add an event listener to the window object (the top-level scope) of your plugin:

window.addEventListener("message", event => {
  console.log("Received from Pendpot::: ", event.data);
})

A quick performance tip: If you’re creating a more complex plugin with different views and perhaps even routes, you need to have a cleanup logic. Most frameworks provide decent ergonomics to do that; for example, React does it via their return statements.

useEffect(() => {
  function handleMessage(e) {
    console.log("Received from Pendpot::: ", event.data);
  }
  window.addEventListener('message', handleMessage);
  
  return () => window.removeEventListener('message', handleMessage);
}, []);

And Solid has onMount and onCleanup helpers for it:

onMount(() => {
  function handleMessage(e) {
    console.log("Received from Penpot::: ", event.data);
  }
  window.addEventListener('message', handleMessage);
})

onCleanup(() => {
  window.removeEventListener('message', handleMessage);
})

Or with the @solid-primitive/event-listener helper library, so it will be automatically disposed:

import { makeEventListener } from "@solid-primitives/event-listener";

function Component() {
  
  const clear = makeEventListener(window, "message", handleMessage);
  
  // ...
  return (<span>Hello!</span>)
}

In the official documentation, there’s a step-by-step guide that will walk you through the process of creating, testing, and publishing your plugin. It will even help you out.

So, what are you waiting for?

Plugin Contest: Imagine, Build, Win

Well, maybe you’re waiting for a push of motivation. The Penpot team thought of that, which is why they’re starting a Plugin Contest!

For this contest, they want a fully functional plugin; it must be open-source and include comprehensive documentation. Detailing its features, installation, and usage. The first prize is US$ 1000, and the criteria are innovation, functionality, usability, performance, and code quality. The contest will run from November 15th to December 15th.

Final Thoughts

If you decide to build a plugin, I’d love to know what you’re building and what stack you chose. Please let me know in the comments below or on BlueSky!

(yk)

This article is sponsored by Penpot

If you’ve been following along with our Penpot series, you’re already familiar with this exciting open-source design tool and how it is changing the game for designer-developer collaboration. Previously, we’ve explored Penpot’s Flex Layout and Grid Layout features, which bring the power of CSS directly into the hands of designers.

Today, we’re diving into another crucial aspect of modern web design and development: components. This feature is a part of Penpot’s major 2.0 release, which introduces a host of new capabilities to bridge the gap between design and code further. Let’s explore how Penpot’s implementation of components can supercharge your design workflow and foster even better collaboration across teams.

About Components

Components are reusable building blocks that form the foundation of modern user interfaces. They encapsulate a piece of UI or functionality that can be reused across your application. This concept of composability — building complex systems from smaller, reusable parts — is a cornerstone of modern web development.

Why does composability matter? There are several key benefits:

• Single source of truth
  Changes to a component are reflected everywhere it’s used, ensuring consistency.
• Flexibility with simpler dependencies
  Components can be easily swapped or updated without affecting the entire system.
• Easier maintenance and scalability
  As your system grows, components help manage complexity.

In the realm of design, this philosophy is best expressed in the concept of design systems. When done right, design systems help to bring your design and code together, reducing ambiguity and streamlining the processes.

However, that’s not so easy to achieve when your designs are built using logic and standards that are much different from the code they’re related to. Penpot works to solve this challenge through its unique approach. Instead of building visual artifacts that only mimic real-world interfaces, UIs in Penpots are built using the same technologies and standards as real working products.

This gives us much better parity between the media and allows designers to build interfaces that are already expressed as code. It fosters easier collaboration as designers and developers can speak the same language when discussing their components. The final result is more maintainable, too. Changes created by designers can propagate consistently, making it easier to manage large-scale systems.

Now, let’s take a look at how components in Penpot work in practice! As an example, I’m going to use the following fictional product page and recreate it in Penpot:

Components In Penpot

Creating Components

To create a component in Penpot, simply select the objects you want to include and select “Create component” from the context menu. This transforms your selection into a reusable element.

Creating Component Variants

Penpot allows you to create variants of your components. These are alternative versions that share the same basic structure but differ in specific aspects like color, size, or state.

You can create variants by using slashes (/) in the components name, for example, by naming your buttons Button/primary and Button/secondary. This will allow you to easily switch between types of a Button component later.

Nesting Components And Using External Libraries

Components in Penpot can be nested, allowing you to build complex UI elements from simpler parts. This mirrors how developers often structure their code. In other words, you can place components inside one another.

Moreover, the components you use don’t have to come from the same file or even from the same organization. You can easily share libraries of components across projects just as you would import code from various dependencies into your codebase. You can also import components from external libraries, such as UI kits and icon sets. Penpot maintains a growing list of such resources for you to choose from, including everything from the large design systems like Material Design to the most popular icon libraries.

Organizing Your Design System

The new major release of Penpot comes with a redesigned Assets panel, which is where your components live. In the Assets panel, you can easily access your components and drag and drop them into designs.

For the better maintenance of design systems, Penpot allows you to store your colors and typography as reusable styles. Same as components, you can name your styles and organize them into hierarchical structures.

Configuring Components

One of the main benefits of using composable components in front-end libraries such as React is their support of props. Component props (short for properties) allow you a great deal of flexibility in how you configure and customize your components, depending on how, where, and when they are used.

Penpot offers similar capabilities in a design tool with variants and overrides. You can switch variants, hide elements, change styles, swap nested components within instances, or even change the whole layout of a component, providing flexibility while maintaining the link to the original component.

Creating Flexible, Scalable Systems

Allowing you to modify Flex and Grid layouts in component instances is where Penpot really shines. However, the power of these layout features goes beyond the components themselves.

With Flex Layout and Grid Layout, you can build components that are much more faithful to their code and easier to modify and maintain. But having those powerful features at your fingertips means that you can also place your components in other Grid and Flex layouts. That’s a big deal as it allows you to test your components in scenarios much closer to their real environment. Directly in a design tool, you can see how your component would behave if you put it in various places on your website or app. This allows you to fine-tune how your components fit into a larger system. It can dramatically reduce friction between design and code and streamline the handoff process.

Generating Components Code

As Penpot’s components are just web-ready code, one of the greatest benefits of using it is how easily you can export code for your components. This feature, like all of Penpot’s capabilities, is completely free.

Using Penpot’s Inspect panel, you can quickly grab all the layout properties and styles as well as the full code snippets for all components.

Documentation And Annotations

To make design systems in Penpot even more maintainable, it includes annotation features to help you document your components. This is crucial for maintaining a clear design system and ensuring a smooth handoff to developers.

Summary

Penpot’s implementation of components and its support for real CSS layouts make it a standout tool for designers who want to work closely with developers. By embracing web standards and providing powerful, flexible components, Penpot enables designers to create more developer-friendly designs without sacrificing creativity or control.

All of Penpot’s features are completely free for both designers and developers. As open-source software, Penpot lets you fully own your design tool experience and makes it accessible for everyone, regardless of team size and budget.

Ready to dive in? You can explore the file used in this article by downloading it and importing into your Penpot account.

As the design tool landscape continues to evolve, Penpot is taking charge of bringing designers and developers closer together. Whether you’re a designer looking to understand the development process or a developer seeking to streamline your workflow with designers, Penpot’s component system is worth exploring.

(yk)

How do you know what UI component to choose? Decision trees offer a systematic approach for design teams to document their design decisions. Once we’ve decided what UI components we use and when, we can avoid never-ending discussions, confusion, and misunderstanding.

Let’s explore a few examples of decision trees for UI components and how we can get the most out of them.

This article is part of our ongoing series on design patterns. It’s also an upcoming part of the 10h-video library on Smart Interface Design Patterns 🍣 and the upcoming live UX training as well. Use code BIRDIE to save 15% off.

B2B Navigation and Help Components: Doctolib

Doctolib Design System is a very impressive design system with decision trees, B2B navigation paths, photography, PIN input, UX writing, and SMS notifications — and thorough guides on how to choose UI components.

• B2B Navigation Patterns Decision Tree
• Form Components Decision Tree
• Actions and Calls To Actions Decision Tree
• Error Design Decision Tree
• Help Component Decision Tree

I love how practical these decision trees are. Each shows an example of what a component looks like, but I would also add references to real-life UI examples and flows of where and how these components are used. A fantastic starting point that documents design decisions better than any guide would.

Decision Trees For UI Components: Workday

The team behind Workday’s Canvas design system created a fantastic set of design decision trees for notifications, errors and alerts, loading patterns, calls to action, truncation, and overflow — with guidelines, examples, and use cases, which can now only be retrieved from the archive:

• Notifications Decision Tree
• Errors and Alerts Decision Tree
• Loading UX Decision Tree
• Calls to Action Decision Tree
• Truncation and Overflow Decision Tree

For each decision tree, the Workday team has put together a few context-related questions to consider first when making a decision before even jumping into the decision tree. Plus, there are thorough examples for each option available, as well as a very detailed alternative text for every image.

Form Components Decision Tree: Lyft

A choice of a form component can often be daunting. When should you use radio buttons, checkboxes, or dropdowns? Runi Goswami from Lyft has shared a detailed form components decision tree that helps their team choose between form controls.

We start by exploring whether a user can select more than one option in our UI. If it’s indeed multi-select, we use toggles for short options and checkboxes for longer ones.

If only one option can be selected, then we use tabs for filtering, radios for shorter options, a switch for immediately applicable options, and a checkbox if only one option can be selected. Dropdowns are used as a last resort.

Choosing Onboarding Components: NewsKit

Onboarding comes in various forms and shapes. Depending on how subtle or prominent we want to highlight a particular feature, we can use popovers, badges, hints, flags, toasts, feature cards, or design a better empty state. The Newskit team has put together an Onboarding Selection Prototype in Figma.

The choice depends on whether we want to interrupt the users to display details (usually isn’t very effective), show a feature subtly during the experience (more effective), or enable discovery by highlighting a feature within the context of a task a user tries to accomplish.

The toolkit asks a designer a couple of questions about the intent of onboarding, and then suggests options that are likely to perform best — a fantastic little helper for streamlined onboarding decisions.

Design System Process Flowcharts: Nucleus

How do you decide to add a new component to a design system or rather extend an existing one? What’s the process for contributions, maintenance, and the overall design process? Some design teams codify their design decisions as design system process flowcharts, as shown below.

• Contribution Process at British Gas
• Contributing Guidelines at Nordhealth
• Processes at Aviva
• Contribution Process at OpenCollective
• Contribution Process at Zalando

And here are helpful decision trees for adding new components to a design system:

• New Component Decision Tree at Boston Scientific
• Handling New Patterns at GitHub
• Design System Governance Process by Brad Frost
• New Component Decision Tree by Louis Ouriach
• Design System Contribution Template by Chad Bergman
• How To Launch A New Component + Figma template by Rama Krushna Behera

Make Decision Trees Visible

What I absolutely love about the decision tree approach is not only that it beautifully visualizes design decisions but that it also serves as a documentation. It establishes shared standards across teams and includes examples to follow, with incredible value for new hires.

Of course, exceptions happen. But once you have codified the ways of working for design teams as a decision tree and made it front and center of your design work, it resolves never-ending discussions about UI decisions for good.

So whenever a debate comes up, document your decisions in a decision tree. Turn them into posters. Place them in kitchen areas and developer’s and QA workspaces. Put them in design critique rooms. Make them visible where design work happens and where code is being written.

It’s worth mentioning that every project will need its own custom trees, so please see the examples above as an idea to build upon and customize away for your needs.

Meet Smart Interface Design Patterns

If you are interested in similar insights around UX, take a look at Smart Interface Design Patterns, our 10h-video course with 100s of practical examples from real-life projects — with a live UX training later this year. Everything from mega-dropdowns to complex enterprise tables — with 5 new segments added every year. Jump to a free preview.

100 design patterns & real-life examples.
10h-video course + live UX training. Free preview.

(yk)

This article is sponsored by Penpot

It was less than a year ago when I first had a chance to use Penpot and instantly got excited about it. They managed to build something that designers haven’t yet seen before — a modern, open-source tool for everyone. In the world of technology, that might not sound groundbreaking. After all, open-source tools and software are being taken for granted as a cornerstone of modern web development. But for some reason, not for design — until now. Penpot’s approach to building design software comes with a lot of good arguments. And it gathered a strong community.

One of the reasons why Penpot is so exciting is that it allows creators to build user interfaces in a visual environment, but using the same standards and technologies as the end product. It makes a design workflow easier on many levels. Today, we are going to focus on just one of them, building layouts.

Design tools went a long way trying to make it easier to design complex, responsive layouts and flexible, customizable components. Some of them tried to mimic the mechanisms used in web technologies and others tried to mimic these imitations. But such an approach will take you only so far.

Short History Of Web Layouts

So how are the layouts for the web built in practice?

If you’ve been around the industry long enough, you might remember the times when you used frames, tables, and floats to build layouts. And if you haven’t, you didn’t miss much. Just to give you a taste of how bad it was: same as exporting tiny images of rounded corners from ever-crashing Photoshop, just to meticulously position them in every corner of a rectangle so you could make a dull, rounded button, it was just a pain. Far too often, it was a pleasure to craft yet another amazing design — but so much tears and sorrow to actually implement it.

Then Flexbox came in and changed everything. And soon after it, Grid. Two powerful yet amazingly simple engines to build layouts that changed web developers’ lives forever.

Ironically, design tools never caught up. Flexbox and Grid opened an ocean of possibilities, yet gated behind a barrier of knowing how to code. None of the design tools ever implemented them so a larger audience of designers could leverage them in their workflows. Not until now.

Creating Layouts With Penpot

Penpot is becoming the first design tool to support both Flexbox and Grid in their toolkit. And by support, I don’t mean a layout feature that tries to copy what Flexbox or Grid has to offer. We’re talking about an actual implementation of Flexbox and Grid inside the design tool.

Penpot’s Flexbox implementation went public earlier this year. If you’d like to give it a try, last year, I wrote a separate article just about it. Now, Penpot is fully implementing both Flexbox and Grid.

You might be wondering why we need both. Couldn’t you just use Flexbox for everything, same as you use the same simple layout features in a design tool? Technically, yes, you could. In fact, most people do. (At the time of writing, only a quarter of websites worldwide use CSS Grid, but its adoption is steadily increasing; source)

So if you want to build simple, mostly linear layouts, Flexbox is probably all you’ll ever need. But if you want to gain some design superpowers? Learn Grid.

Penpot’s CSS Grid Layout is out now, so you can already give it a try. It’s a part of their major 2.0 release, bringing a bunch of long-awaited features and improvements. I’d strongly encourage you to give it a go and see how it works for yourself. And if you need some inspiration, keep reading!

CSS Grid Layout In Practice

As an example, let’s build a portfolio page that consists of a sidebar and a grid of pictures.

Creating A Layout

Our first step will be to create a simple two-dimensional grid. In this case using a Grid Layout makes more sense than Flex Layout as we want to have more granular control over how elements are laid out on multiple axes.

You can notice that each row and column of the layout has a value of “1FR”. FR stands for fraction, which means that the available space will be distributed evenly across rows and columns.

FRs are extremely useful. For example, the same as other units, FRs can take different values. So you could create 3 columns, one taking 2FRs and two counting 1FR each. As a result, the first column would occupy half of the layout’s width and the other two would take a quarter of available space each.

Adding Elements To The Layout

To add elements to CSS Grid Layout, you can simply drag and drop them onto the canvas.

For each element you can either assign it to a dedicated cell of the grid or allow it to find its place on its own and fill the first available blank.

Spacing And Alignment

CSS Grid Layout gives you full control over how the elements are aligned and how they adjust to available space. A plethora of highly granular options allows you to create very precise, responsive layouts that work seamlessly with elements of any shape or form.

You can make cells and rows adjust to the size of the elements but you can also make the elements adjust to the grid. In this case, we are going to add a sidebar on the left side of the layout and place it in a column with a fixed width of 320px.

The sidebar itself has its own layout. But in this case, for the simple vertical alignment, the Flex Layout is all we need.

Creating Grid Areas

To make the grid even more powerful, you can merge cells, group them into functional areas, and name them. Here, we are going to create a dedicated area for the sidebar.

As you adjust the layout later, you can see that the sidebar always keeps the same width and full height of the design while other cells get adjusted to the available space.

Building Even More Complex Grids

That’s not all. Apart from merging cells of the grid, you can tell elements inside it to take multiple cells. On our portfolio page, we are going to use this to make the featured picture bigger than others and take four cells instead of one.

As a result, we created a complex, responsive layout that would be a breeze to turn it into a functional website but at the same time would be completely impossible to build in any other design tool out there. And that’s just a fraction of what Grid Layout can do.

Next Steps

I hope you liked this demo of Penpot’s Grid Layout. If you’d like to play around with the examples used in this article, go ahead and duplicate this Penpot file. It’s a great template that explains all the ins and outs of using Grid in your designs!

In case you’re more of a video-learning type, there’s a great tutorial on Grid Layout you can watch now on YouTube. And if you need help at any point, the Penpot community will be more than happy to answer your questions.

Summary

Flexbox and Grid in Penpot open up opportunities to craft layouts like never before. Today, anyone can combine the power of Flex Layout and Grid Layout to create complex, sophisticated structures that are flexible, responsive, and ready to deploy out-of-the-box—all without writing a single line of code.

Working with the right technologies not only makes things easier, but it also just feels right. That’s something I’ve always longed for in design tools. Adopting CSS as a standard for both designers and developers facilitates smoother collaboration and helps them both feel more at home in their workflows.

For designers, that’s also a chance to strengthen their skill set, which matters today more than ever. The design industry is a competitive space that keeps changing rapidly, and staying competitive is hard work. However, learning the less obvious aspects and gaining a better understanding of the technologies you work with might help you do that.

Try CSS Grid Layout And Share Your Thoughts!

If you decide to give CSS Grid Layout a try, don’t hesitate to share your experience! The team behind Penpot would love to hear your feedback. Being a completely free and open-source tool, Penpot’s development thrives thanks to its community and people like you.

(il)

Remember the “mobile first” mantra? The idea was born out of the early days of responsive web design. Rather than design and build for the “desktop” up front, a “mobile-first” approach treats small screens as first-class citizens. There’s a reduced amount of real estate, certainly less than the number of pixels we get from the viewport of Firefox expanded fullscreen on a 27-inch studio monitor.

The constraint is a challenge to make sure that whatever is sent to mobile devices is directly relevant to what users should need; nothing more, nothing less. Anything more additive to the UI can be reserved for wider screens where we’re allowed to stretch out and make more liberal use of space.

/* A sample CSS snippet for a responsive main content */

/* Base Styles */
.main-content {
  container: main / inline-size;
}

.gallery {
  display: grid;
  gap: 1rem;
}

/* Container is wider than or equal to 700px */
@container main (width >= 700px) {
  .gallery {
    grid-template-columns: 1fr 1fr;
  }
}

/* Container is wider than or equal to 1200px */
@container main (width >= 1200px) {
  .gallery {
    grid-template-columns: repeat(4, 1fr);
  }
}

Now, I’m not here to admonish anyone who isn’t using a mobile-first approach when designing and building web interfaces. If anything, the last five or so years have shown us just how unpredictable of a medium the web is, including what sort of device is displaying our work all the way down to a user’s individual preferences.

Even so, there are things that any designer and developer should consider when working with mobile interfaces. Now that we’re nearly 15 years into responsive web design as a practice and craft, users are beginning to form opinions about what to expect when trying to do certain things in a mobile interface. I know that I have expectations. I am sure you have them as well.

I’ve been keeping track of the mobile interfaces I use and have started finding common patterns that feel mobile in nature but are more desktop-focused in practice. While keeping track of the mobile interfaces I use, I’ve found common patterns that are unsuitable for small screens and thus could use some updates. Here are some reworked features that are worth considering for mobile interfaces.

Economically-Sized Forms

There are myriad problems that come up while completing mobile forms — e.g., small tap targets, lack of offline support, and incorrect virtual keyboards, to name a few — but it’s how a mobile form interacts with the device’s virtual keyboard that draws my ire the most.

The keyboard obscures the form more times than not. You tap a form field, and the keyboard slides up, and — poof! — it’s as though half the form is chopped out of view. If you’re thinking, Meh, all that means is a little extra scrolling, consider that scrolling isn’t always a choice. If the page is a short one with only the form on it, it’s highly possible what you see on the screen is what you get.

A more delightful user experience for mobile forms is to take a “less is more” approach. Display one form field at a time for an economical layout that allows the field and virtual keyboard to co-exist in harmony without any visual obstructions. Focusing the design on the top half of the viewport with room for navigation controls and microcopy creates a seamless flow from one form input to the next.

More Room For Searching

Search presents a dichotomy: It is incredibly useful, yet is treated as an afterthought, likely tucked in the upper-right corner of a global header, out of view and often further buried by hiding the form input until the user clicks some icon, typically a magnifying glass. (It’s ironic we minimize the UI with a magnifying glass, isn’t it?)

The problem with burying search in a mobile context is two-fold:

1. The feature is less apparent, and
2. The space to enter a search query, add any filters, and display results is minimized.

That may very well be acceptable if the site has only a handful of pages to navigate. However, if the search allows a user to surface relevant content and freely move about an app, then you’re going to want to give it higher prominence.

Any service-oriented mobile app can improve user experience by providing a search box that’s immediately recognizable and with enough breathing room for tapping a virtual keyboard.

“

Some sites even have search forms that occupy the full screen without surrounding components, offering a “distraction-free” interface for typing queries.

No Drop-Downs, If Possible

The <select> element can negatively impact mobile UX in two glaring ways:

1. An expanding <select> with so many options that it produces excessive scrolling.
2. Scrolling excessively, particularly on long pages, produces an awkward situation where the page continues scrolling after already scrolling through the list of <option>s.

I’ll come across these situations, stare at my phone, and ask:

Do I really need a <select> populated with one hundred years to submit my birthdate?

Seems like an awful lot of trouble to sort through one hundred years compared to manually typing in a four-digit value myself.

A better pattern for making list selections, if absolutely needed, in a space-constrained mobile layout could be something closer to the ones used by iOS and Android devices by default. Sure, there’s scrolling involved, but within a confined space that leaves the rest of the UI alone.

A Restrained Overview

A dashboard overview in a mobile app is something that displays key data to users right off the bat, surfacing common information that the user would otherwise have to seek out. There are great use cases for dashboards, many of which you likely interact with daily, like your banking app, a project management system, or even a page showing today’s baseball scores. The WordPress dashboard is a perfect example, showing site activity, security checks, traffic, and more.

Dashboards are just fine. But the sensitive information they might contain is what worries me when I’m viewing a dashboard on a mobile device.

Let’s say I’m having dinner with friends at a restaurant. We split the check. To pay my fair share, I take out my phone and log into my banking app, and… the home screen displays my bank balance in big, bold numbers to the friends sitting right next to me, one of whom is the gossipiest of the bunch. There goes a bit of my pride.

That’s an extreme illustration because not all apps convey that level of sensitive information. But many do, and the care we put into protecting a user’s information from peeping eyeballs is only becoming more important as entire industries, like health care and education, lean more heavily into online experiences.

My advice: Hide sensitive information until prompted by the user to display it.

It’s generally a good practice to obscure sensitive information and have a liberal definition of what constitutes sensitive information.

“

Shortcuts Provided In The Login Flow

There’s a natural order to things, particularly when logging into a web app. We log in, see a welcome message, and are taken to a dashboard before we tap on some item that triggers some sort of action to perform. In other words, it takes a few steps and walking through a couple of doors to get to accomplish what we came to do.

What if we put actions earlier in the login flow? As in, they are displayed right along with the login form. This is what we call a shortcut.

Let’s take the same restaurant example from earlier, where I’m back at dinner and ready to pay. This time, however, I will open a different bank app. This one has shortcuts next to the login form, one of which is a “Scan to Pay” option. I tap it, log in, and am taken straight to the scanning feature that opens the camera on my device, completely bypassing any superfluous welcome messaging or dashboard. This spares the user both time and effort (and prevents sensitive information from leaking into view to boot).

Mobile operating systems also provide options for shortcuts when long-pressing an app’s icon on the home screen, which also can be used to an app’s advantage.

The Right Keyboard Configuration

All modern mobile operating systems are smart enough to tailor the virtual keyboard for specialized form inputs. A form field markup with type="email", for instance, triggers an onscreen keyboard that shows the “@” key in the primary view, preventing users from having to tap Shift to reveal it in a subsequent view. The same is true with URLs, where a “.com” key surfaces for inputs with type="url".

The right keyboard saves the effort of hunting down relevant special characters and numbers for specific fields. All we need to do is to use the right attributes and semantics for those fields, like, type=email, type=url, type=tel, and such.

<!-- Input Types for Virtual Keyboards -->
<input type="text">   <!-- default -->
<input type="tel">    <!-- numeric keyboard -->
<input type="number"> <!-- numeric keyboard -->
<input type="email">  <!-- displays @ key -->
<input type="url">    <!-- displays .com key -->
<input type="search"> <!-- displays search button -->
<input type="date">   <!-- displays date picker or wheel controls -->

Bigger Fonts With Higher Contrast

This may have been one of the first things that came to your mind when reading the article title. That’s because small text is prevalent in mobile interfaces. It’s not wrong to scale text in response to smaller screens, but where you set the lower end of the range may be too small for many users, even those with great vision.

The default size of body text is 16px on the web. That’s thanks to user agent styling that’s consistent across all browsers, including those on mobile platforms. But what exactly is the ideal size for mobile? The answer is not entirely clear. For example, Apple’s Human Interface Guidelines do not specify exact font sizes but rather focus on the use of Dynamic Text that adjusts the size of content to the user’s device-level preferences. Google’s Material Design guidelines are more concrete but are based on three scales: small, medium, and large. The following table shows the minimum font sizes for each scale based on the system’s typography tokens.

The real standard we ought to be looking at is the current WCAG 2.2, and here’s what it says on the topic:

“When using text without specifying the font size, the smallest font size used on major browsers for unspecified text would be a reasonable size to assume for the font.”

So, bottom line is that the bottom end of a font’s scale matches the web’s default 16px if we accept Android’s “Small” defaults. But even then, there are caveats because WCAG is more focused on contrast than size. Like, if the font in use is thin by default, WCAG suggests bumping up the font size to produce a higher contrast ratio between the text and the background it sits against.

There are many, many articles that can give you summaries of various typographical guidelines and how to adhere to them for optimal font sizing. The best advice I’ve seen, however, is Eric Bailey rallying us to “beat the “Reader Mode” button. Eric is talking more specifically about preventing clutter in an interface, but the same holds for font sizing. If the text is tiny or thin, I’m going to bash that button on your site with no hesitation.

Wrapping Up

Everything we’ve covered here in this article is personal irritations I feel when interacting with different mobile interfaces. I’m sure you have your own set of annoyances, and if you do, I’d love to read them in the comments if you’re willing to share. And someone else is likely to have even more examples.

The point is that we’re in some kind of “post-responsive” era of web design, one that looks beyond how elements stack in response to the viewport to consider user preferences, privacy, and providing optimal experiences at any breakpoint regardless of whatever device is used.

(gg, yk)