Usage guidance.
Decision trees and compact Do / Don't rules for choosing BR-UI primitives without inventing new interaction language per screen.
Decision Trees
| When you need | Use | Avoid | Why |
|---|---|---|---|
| Status, count, or plan label? | Badge | Chip | Badge is read-only metadata. Chip is an interactive filter or removable token. |
| One-shot hint for an icon or terse control? | Tooltip | Dropdown | Tooltip explains. Dropdown offers actions. Never hide required action choices inside hover-only UI. |
| Several related actions from one trigger? | Dropdown | Tooltip | Dropdowns are command surfaces with keyboardable items, separators, labels, and shortcuts. |
| Blocking confirmation or destructive decision? | Dialog | Sheet | Dialogs interrupt by design. Sheets are for side-context editing that can be dismissed safely. |
| Large side edit flow tied to the current page? | Sheet | Dialog | Sheets preserve page context and keep the working object visible behind the scrim. |
| Mobile-first bottom action or upload handoff? | Drawer | Sheet | Drawer reads as a temporary tray. Use it for short, tactile flows rather than dense forms. |
| Switching views within the same data set? | Tabs | Stepper | Tabs are peer views. Stepper implies ordered progress and validation between steps. |
| Metric, evidence, or story surface? | StatCard / CaseCard | Generic Card | Use the named card when the content has a known information shape and rhythm. |
Do / Don't
Keep one primary action per surface and label every icon-only button.
Do not stack primary buttons or rely on an icon as the accessible name.
Use the BR danger treatment, which stays accent-led and editorial.
Do not introduce unrelated red palettes unless a product domain explicitly requires status red.
Pair every table with empty, loading, and error states before wiring real data.
Do not ship a happy-path table without pagination, sorting intent, or a no-data state.
Show field errors next to controls and summarize blocking errors at form level.
Do not depend on color alone for invalid state or leave submit buttons active while submitting.
Give each chart a readable title, accessible label, and no-data fallback.
Do not render decorative SVG charts without a screen-reader name or fallback state.
Use spacing tokens and the variant density rules instead of custom per-screen padding.
Do not hard-code one-off margins that will collapse under variant C or mobile layouts.