Example mapping

A timeboxed conversation that takes one story and breaks it into four kinds of card. It is the most mechanical of the practices here and the one that most reliably pays for itself on the first attempt.

It was created by Matt Wynne, co-founder of Cucumber, in his 2015 article Introducing Example Mapping.

The four card colours are Matt Wynne’s; a ready-made template and walkthrough is at draft.io/example/example-mapping. The state card is the addition this hub makes — and most of them are answered by the design system in the room rather than designed in the session.

The four colours

Card	Colour	What it holds
Story	Yellow	The one under discussion. There is exactly one.
Rule	Blue	A constraint or acceptance criterion.
Example	Green	A concrete case illustrating a rule — real values, not “some input”.
Question	Red	Something nobody in the room can answer.

Twenty-five minutes, no longer. Write the story. Write the rules under it. Under each rule, write examples until everyone agrees the rule is understood. Whenever someone says “it depends” or “I’d have to check”, that is a red card — write it and move on rather than speculating.

The four amigos

The room is the four amigos: product owner, developer, quality engineer and UX designer. The designer is not a guest — the session has a whole class of rule that the other three reliably miss.

The three ask what must be true. The designer asks what does the person see when it is not — and that second question is where interfaces actually fail.

The designer also brings the design system into the room, which is what stops the next section from turning a twenty-five-minute session into a design workshop.

The hard states

The addition to the practice: a pass over each rule asking what the person experiences when the rule’s happy case does not hold. Each answer is a state card (purple, in the diagram above) attached to a rule, and it is treated as a first-class output of the session rather than as an implementation detail.

The checklist, in the order they are usually forgotten:

State	The question	Why it is missed
Empty	First run, nothing here yet	Demos always have data
Partial	Some of it loaded, some failed	Nobody designs for half
Slow	It is taking eight seconds	The developer’s machine is fast
Denied	They are not allowed	Permissions arrive after the design
Offline	The network went away mid-task	Rarely reproduced on purpose
Too many	Four thousand rows, not four	Test data is small
Too long	A name of ninety characters	Test data is polite
Wrong locale	A different date order, a longer word, right-to-left	Discovered at translation
Stale	It changed underneath them while they were reading	Requires thinking about time
Irreversible	This one cannot be undone	The confirmation is added after the first incident

Not every state applies to every rule. Running the checklist takes about four minutes and typically produces two or three real cards — and each of those is a question that would otherwise have been answered by an assumption, silently, by whoever hit it first.

Check each one against the system first

This is the step that keeps the session inside its twenty-five minutes.

The design system is an input to this session, not something it produces. So a state card is not a design task; it is a lookup, with three possible answers:

Answer	What happens	How often
Covered. The system has this state, and the library component already expresses it	Note the card, move on. Ten seconds	Most of the time
Composable. No single component covers it, but the existing pieces do	Note how, move on. A minute	Sometimes
Uncovered. Nothing in the system answers it	The card survives as a change request against the contract, decided by its owners	Rarely, and it is the valuable output

A team whose example maps produce a designed state per card does not have a design system yet — it has a folder of past decisions. The measure of an established contract is precisely how few cards fall into the third row.

What must not happen is the fourth answer: the story quietly builds its own version of an uncovered state, inside one screen, where no other feature will ever find it.

Reading the map

The shape of the finished map tells you what to do next, before anyone discusses it:

• Many red cards — the story is not ready. Do not estimate it.
• Many blue cards — the story is too big. Split it along the rules.
• A rule with no green cards — nobody actually understands that rule yet.
• A rule with no state cards — either it genuinely has no failure mode, or nobody looked. It is usually the second.
• Many uncovered state cards — the story is pushing into territory the contracts do not reach. That is worth knowing before it is estimated, and it usually means a change request has to land first.
• Few cards, quick agreement — the story is ready. This is the good outcome and it takes ten minutes.

Where each card goes afterwards

Nothing is retyped. That is the whole reason the session produces cards rather than a document.

Card	Becomes
Green example	A scenario in the journey test, with the same values
State card, covered	A note in the story saying which established state to use — no new work
State card, uncovered	A change request against the design system or the core library, decided upstream
Blue rule	An acceptance criterion, and often a domain invariant
Red question	A research or product task, tracked; it must be closed before the story is estimated

The state card is what closes the loop this hub is about. A state that appears on a card is either already answered by the contracts — in which case it arrives with a design, a token, a component story, an interaction test and an accessibility scan, all of which already exist — or it is named as missing and fixed once, upstream, for everybody.

A state that never appears on a card gets none of that, and it still ships.

The formal step

Example mapping is where a story stops being a description and starts being executable. A green card is the moment a sentence acquires values — “a basket of 50.00 CHF”, “a name of ninety characters” — and a sentence with values has an outcome someone can observe.

features/checkout/redeem-a-voucher.feature

Feature: Redeem a voucher

  Rule: A voucher must not be expired

    Example: A voucher that expired yesterday is refused
      Given a voucher "SPRING20" that expired yesterday
      When the customer applies it to a basket of 50.00 CHF
      Then the voucher is refused
      And the basket total is unchanged
      And the reason is shown next to the voucher field

  Rule: The customer can always see why a voucher was refused

    Example: The refusal is announced, not only shown
      Given the voucher was refused
      Then the reason is associated with the voucher field
      And it is announced by assistive technology

The last two lines are what the designer’s presence adds. Without them the rule is satisfied by red text that a screen reader never mentions, which is a passing test and a failed interface. Both lines are cheap to satisfy here because the established field component already announces its own errors — the scenario is asserting a guarantee the contract makes, not requesting a new one.

Two rules follow, and both are cheap to apply:

• Do not write scenarios in narrative. “Then the discount is applied correctly” is a narrative sentence wearing Gherkin’s clothes. Correctly is the word that survived the translation, and it carries no value anyone can check.
• Do not write a state card as a mood. “Then a nice empty state is shown” is the same failure. Name what is on the screen and what it offers the person to do next.

Not story mapping

Different axis, different session. Story mapping works across the whole journey and decides which stories exist and in what order; this works on one story and decides what it means. The map picks the next card to open; example mapping opens it.

The official source

draft.io/example/example-mapping carries a usable template, the four-colour convention and a walkthrough, and points back at Matt Wynne’s original article.