avatar stack tokens: the four decisions nobody named

avatar stack tokens: the four decisions nobody named

Every “who’s online” stack in your product already has an overlap amount, a visible cap, a ring width, and a ring color, whether anyone decided them on purpose or not.

Avatar stacks tend to get built the same way toast notifications do: fast, by whoever needed one first, with no system behind the choice. One component overlaps its circles by four pixels. Another overlaps by nineteen, because a different engineer eyeballed it against a mockup that was never measured. A third skips the ring entirely, so overlapping avatars blur into each other with no separation at all. None of this is a bug in any single component. It is the absence of a decision that was supposed to be made once, at the system level, instead of once per component.

Four custom properties name the decision instead of leaving it to whoever ships next. `--avatar-overlap` is the one offset every stack shifts by, so a five-person "who's reviewing this" row and a twelve-person "who's online" row read as the same material instead of two different ideas about how close is too close. `--avatar-stack-max` caps how many circles render before the rest collapse into a count, so a busy channel doesn't wallpaper the header with faces. `--avatar-ring-width` and `--avatar-ring-color` name the border that separates one overlapping circle from the next, the one detail that makes a stack of five read as five distinct people instead of a blurred Venn diagram. None of these are colors in the usual sense. They are spacing and separation decisions, which is exactly why they get skipped: nothing about them fails a design review the way a wrong hex code does, right up until two avatars overlap so far that half a face disappears behind another.

Watch the reel on Instagram. Link going live 2026-11-08 (Sun).

Applying the recipe is a handful of variables read by one avatar-stack component, not four separate fixes scattered across a codebase. Every place a group of people renders, from a comment thread to a live cursor list, points at the same overlap math and the same cap, so the difference between surfaces is the data, never the geometry. A design system that only tokenizes what shows up in a style guide, color, type, spacing, misses the components that only appear when more than one person is present and are easy to dismiss as "just avatars" right up until a product has real concurrent users and the stack is the first thing that looks unfinished.

Follow @march4orthdesign on Instagram for the next one.

https://www.march4orthdesign.com/m4d-projects/download.html