Pattern Library

Collecting parts settled early as a practice. Build the button and the text field once, put them in a component library, and no screen has to draw them again. Yet teams with a complete set of parts kept producing screens that disagreed with each other.

The disagreement lived in situations, not parts. Deleting a document raised a modal asking "are you sure?" on one screen, while another screen deleted silently and reported it with a toast. A modal blocks the screen behind it; a toast appears briefly and disappears. Both were sanctioned parts, so nobody had broken a rule. It was simply written down nowhere which of the two was the standard.

The problem surfaced when Noa posted a design for a new list screen. Review brought the question "we did that screen differently last quarter, so why this way now?" and nobody could say which version was correct. The decision had been made, twice, and never recorded either time.

A pattern library is where that record lives. If the parts answer "this is what the button looks like," this answers "we ask before deleting." Parts are nouns; patterns read more like sentences. The distinction matters because the second kind of question comes up far more often than the first, and it is the kind that gets answered in a hallway and then forgotten.

Each entry covers one situation, and an entry usually holds six things.

1. The name of the situation — written as a situation, not as a part. Not "confirmation modal" but "getting confirmation for an irreversible delete." Named that way, whoever builds the next screen searches by the situation they are actually in.
2. When it applies and when it doesn't — the boundary. Write down that reversible deletes get an undo instead of a question, and confirmation dialogs stop spreading across the whole product.
3. The solution — which parts, in what order. This goes past naming the parts, down to what the title says and which side each button sits on.
4. Screen examples — a correct use and a violation side by side. Without the violation, a reader has no way to feel where the boundary runs.
5. The words — title, body, and button labels, all settled. Leave the microcopy open and five screens using the same pattern end up with five different button labels.
6. Reasoning and exceptions — why it was decided this way, plus the exceptions already allowed. With no reasoning recorded, the same debate restarts from zero six months later.

Which situations the library covers varies by product, though some recur everywhere: confirming irreversible actions, the empty state shown when there is nothing to display, the error message after a failed save, alerts for input that breaks a rule, and progress for anything slow. Starting under twenty entries and adding situations as the team actually hits them works better than trying to be complete. A shorter library that matches the product beats a long one describing screens nobody shipped.

A designer writes it, but not alone. Engineers know what the screen can actually do, and whoever owns UX writing reviews the words. UX writing is the practice of guiding users through the text inside a product.

When an entry gets written determines what kind of document this is. A pattern is not a plan for how things will be done; it is the record of a decision already made. Solve the same situation on two or three screens, judge which approach held up better, then write it. An entry written before anything was built breaks on the first real screen, and a few broken entries are enough for a team to stop trusting the document.

Three kinds of people read it.

1. A designer starting a new screen — checks whether the situation is already settled before drawing anything. If it is, that part of the screen becomes a choice rather than a decision.
2. An engineer — looks up the cases the design file left out. Design files show the path where everything works; the failure states are usually missing.
3. Someone who just joined — learns why the team does things this way without having to ask a person, which also spares the people who would otherwise answer the same question every month.

If nobody owns keeping it current, this is the first document to rot. When screens change and entries don't, readers can't tell which version is today's, and from then on not reading is the safer bet. Many teams put a last-edited date and an owner on every entry for exactly that reason.

"That situation is in the pattern library. We settled on asking only when the delete can't be undone."

The decision already exists, so don't remake it here.

"There are parts but no patterns, so every screen solves it differently."

The component set is complete; the situation-level solutions were never recorded.

"This one breaks the pattern. Do we log it as an exception or change the pattern?"

Sorting a one-time deviation from a real shift in the standard.

Pagedeck started this document after passing sixty screens. Noa's first move was not to write entries but to walk the existing screens and count how many ways each situation had been solved. Delete confirmation came back with four variants, empty states with seven.

Picking which variant became the standard happened with Theo. They chose the version that cost least to converge on, rather than the one already used on the most screens. Twelve entries went in to start, and after that an entry got added each time a new screen forced a fresh decision.

The most common reading treats a pattern library as the documentation half of a component library. Both sit inside the design system and the names are close, so it looks that way. But the unit differs. The component side covers one button's sizes and states; the pattern side covers a flow built from several parts. Treat them as the same thing, tuck patterns inside part documentation, and whoever opens the button page never finds the delete-confirmation rule — which means that rule splits by screen all over again.

Assuming more entries make a better document is also frequent. A hundred entries look reassuring, but if only twenty were validated on real screens, the other eighty cast doubt on those twenty as well. Readers have no way to tell which entries are live, so they stop reading all of them. Counting entries is the wrong measure; what matters is whether each one points at a screen that exists.