Components
Components
Every UI element the app uses. Start with the decision table, then open the page for the group you need.
#Which component?
Find what the person needs to do or see, and use the component in the right-hand column. If nothing fits, compose existing ones before proposing a new one.
| The person needs to… | Use | Page |
|---|---|---|
| Start or confirm something (save, connect, continue) | .btn .btn-primary, one per view | Button |
| Go somewhere else in the product | .btn-link or a nav item | Inline link |
| Do something risky or irreversible | .btn-danger, never the primary | Button |
| See a status (ready, waiting, failed, latest) | Pill with a tone | Pill |
| Type something in | .field with a label | Field |
| Choose one of a few options at once | Segmented control | Theme switch |
| Answer “how are we doing?” | Pulse strip of metric tiles | Metric tile |
| See a change against last week | Delta | Delta |
| See the recent shape of a number | Sparkline | Sparkline |
| Compare items in one list (products, channels) | Rank bars | Rank bars |
| Browse past weekly packs | Weekly timeline | Timeline |
| Know the one thing to do this week | Action band | Action band |
| Know a report is on its way | Status panel | Status panel |
| Leave Weekwright to pay or approve access | Handoff modal | Handoff |
| Find a page, store, or report | Sidebar and breadcrumb | Sidebar |
| Group related content | .card, with an .inset inside | Card |
#The groups
ComponentsComponentsEvery UI element the app uses. Start with the decision table, then open the page for the group you need.ComponentsActions and inputsButtons, links, pills, fields, and the theme switch. The things a person presses, reads as a label, or types into.ComponentsData displayMetric tiles, deltas, sparklines, rank bars, the weekly timeline, and store cards. How numbers appear, and how direction comes before decimals.ComponentsFeedback and overlaysThe action band, the first-report status panel, the handoff modal, and how to show loading, empty, and error states without fuss.ComponentsNavigation and structureThe sidebar, page header, breadcrumb, back link, cards, and insets. How people find their way and how content is grouped.
#Rules that apply to every component
Use roles, never raw valuesColors, spacing, radius, and type come from tokens. A new value becomes a token first.
Compose before you createPrefer existing primitives to page-specific CSS. Inline
style is only for data, such as a bar width.Status is never color alonePair color with words, an arrow, or an icon. Test it in grayscale.
Both themes, every timeA component is not done until it reads in light and dark. Use the Light and Dark buttons on each specimen here.
Keyboard firstEverything interactive shows a 2px focus ring, is reachable by Tab, and works with Enter or Space.
Ship a testIn the app, every component and page file needs 100% test coverage. New primitives arrive with tests.
#Adding a component
- Check the table above. Could an existing component do the job?
- Add tokens first, then CSS in the app’s
components.css, then a React primitive only if it carries logic. - Add a tested example in the app, then run
npm run synchere and add a specimen page entry with “use when” and “don’t use when”. - Add a row to the table above.