Decisions
The major, cross-cutting choices behind the system, what they were weighed against, and the questions still open.
A decision record writes down a major choice that cuts across the system: one that changes a principle, a material or the meaning of a color, applies across products, or overrides what the product does. Each record says what the situation was, what was decided, what follows from it and what it was weighed against, so the choice can be revisited without guessing why it was made.
Smaller rules don't get a record. Their reason is written next to the rule, in the page that owns it: a foundation, a pattern, a component doc, the content section, people and agents, or the principles.
- Numbers are never reused or renumbered. A gap in the numbers is a record whose rule now lives, with its reason, in the page that owns it; its old address redirects there.
- A record that a later choice overrides is marked
supersededand links the record that replaced it. - A choice that isn't made yet goes in Open questions, with the default to use until it is made.
How to write a record is in Authoring and the decision template.
- Open questionsThe places where the system has drawn more than one version and the choice is still open, with the current default for each, and the questions the product has settled.
- Pink is lighter than the product's pinkThe attention pink is lighter than the product code's pink, so that ink on it reaches the same contrast as the other sticker colors.
- No all caps, including group headings and dialog titlesGroup headings, dialog titles and badges use sentence case instead of the product code's all caps.
- Working agents are shown where they appear, not in a live barWhat agents are doing is written in the places they already appear, instead of in a live bar above the tab bar or at the bottom of the sidebar.
- Regions are separated by a 45% ink seam, and controls have no shadowLines between regions are 1px `line-seam` at 45% ink instead of 2px black, and only brand illustration has a hard shadow.
- Selection in navigation is a yellow stickerThe selected sidebar row and settings navigation item is a yellow sticker instead of pink with a hard shadow.
- In dark mode the frame is neutral, but the rail's selection stays yellowIn dark mode the frame is a neutral dark, and the selected rail item is still a yellow sticker.
- Unread is pink with ink text, everywhereEvery unread count is pink with ink text, including new thread replies.
- Stickers and square avatars stay the same in dark modeIn dark mode, buttons, chips and avatars stay stickers, instead of the product's Elegant washes and round avatars.