In a design system, how should usage guidance help teams choose between look-alike components such as a toast and an inline banner?

## Why look-alikes need their own guidance In a **design system** — the shared tokens, components, patterns and guidance that many product teams build from — some components look alike on purpose because they share a visual family. A **toast** (a brief message that appears over the interface and usually goes away on its own), an **inline banner** (a message placed in the page near the content it concerns, which stays until dismissed or resolved) and an **inline field message** (text attached to one input) can all be a coloured strip with an icon and a sentence. Teams that choose by appearance pick whichever matches the mockup, and the same situation ends up handled three different ways across the product. Guidance for look-alikes therefore has a different job from ordinary usage guidance: not 'is this component right?' but 'which of these siblings is right?' ## Decide by situation, not appearance Turn the choice into a small set of **deciding questions**, phrased in terms of the person using the product rather than the component's visuals: 1. **Must the message stay until it is resolved**, or is it acceptable if the person misses it? 2. **Must the person act** — fix, confirm or choose something — before continuing? 3. **What does it concern**: one field, one section of the page, or the whole task? 4. **How urgent is it**: does it block progress or merely inform? Three or four questions are usually enough. More than that and the guidance becomes a flowchart nobody follows. ## One comparison table for the family Answer the deciding questions once, in a table that every sibling's page shows or links to. On a car-rental site it might read: | Situation | Must persist? | Action needed? | Scope | Fits | |---|---|---|---|---| | 'Pickup time saved' | No | No | Whole task | Toast | | 'Your licence expires before the return date' | Until fixed | Yes | This booking | Inline banner | | 'Enter a valid postcode' | Until fixed | Yes | One field | Inline field message | The exact rules vary between systems — many allow a single undo action inside a toast, for instance — so the table records *this* system's decisions. Its value is that there is exactly one version of it: comparisons written separately on each page tend to drift apart until two pages give opposite answers to the same choice. ## Reciprocal 'use instead' links Each sibling's **when not to use** section should name the sibling that fits instead, and the links should run both ways: - On the toast page: 'Don't use a toast for a problem the renter must fix — it can disappear before it is read. Use an inline banner beside the affected booking.' - On the inline banner page: 'Don't use a banner to confirm a routine save — it adds clutter that stays on screen. Use a toast.' - On the field message page: 'Don't repeat a single field's error in a page-level banner unless several fields fail at once.' A reader who lands on the wrong page is one step from the right one, and the reason travels with the redirect. ## Show the same scenario both ways The most persuasive example is one real scenario rendered correctly and incorrectly. The renter's licence-expiry message shown as a toast that vanishes after a few seconds, next to the same message as a banner pinned above the booking, makes the persistence question concrete in a way no definition does. Keep the pair minimal — change only the component — so the lesson is unambiguous, and label it with text and an icon, not colour alone. ## When the table has a gap Sometimes a situation fits no row: a licence check that is still processing and will finish in a few minutes is neither a problem to fix nor a confirmation. Resist writing a one-off exception into the guidance that stretches the nearest component. Instead: - record the gap on the comparison table, openly; - name the closest safe choice for now; - send the need into the system's contribution process so it can be designed deliberately. A table that shows its gap honestly is more useful than one that forces every case into an existing box. ## Writing it for both audiences Designers and engineers choose from different places — a design editor's library and a code package, on the web and on native mobile — but they face the same user situation. Phrase the deciding questions in user terms, use identical component names on both sides, and put the comparison where each audience makes the choice: the library's component description and the code documentation, not only the documentation website.