@persona/design-system 0.9.1 → 0.10.0

package/skills/ui-authoring/TOKENS.md

@@ -1,151 +1,489 @@
 # Design Tokens
 
-How to pick values from `@persona/design-tokens`, plus the `Color` / `Spacing` / `Typography` catalog.
+How to pick colors (semantic tokens, so the same job looks right in light and dark mode), plus the
+`Spacing` / `Typography` / radius / elevation / chart catalog from `@persona/design-tokens`.
 
 ```tsx
 import { BorderRadius, ChartingColors, Color, Spacing, Typography } from '@persona/design-tokens';
+import { semanticColor } from '@persona/design-system/lib/semanticColor';
 ```
 
 ## Color
 
-`Color` is an enum of named colors organized by purpose (`Text*`, `Background*`, `Border*`, and
-others), plus a `Core*` palette and a `Primary*` brand set.
+Pick the semantic token whose name describes the color's job (`FgPrimary`, `SurfaceElevated`,
+`FeedbackDanger1`, …). The full list is the `SemanticTokens` interface in
+`@persona/design-system/variables/semantic`.
 
-Use according to this priority:
-
-1. Purpose-named `Color.*` (`Text*`, `Background*`, `Border*`, …)
-2. `Color.Core*` / `Color.Primary*` with a comment explaining the choice. For `Core*`, that comment is an `oxlint-disable-next-line rulesdir/no-core-color-tokens`.
-3. Hardcoded hex (only if absolutely necessary) with a comment explaining the choice.
+`Color.*` from `@persona/design-tokens` (`Core*`, `Primary*`, and the purpose-named `Text*` /
+`Background*` / `Border*`) is the fixed palette the semantic tokens point to. It does not follow the
+theme, so it is never the painted color — only the fallback argument, as are old theme values such as
+`theme.color.background.primary`. Hardcode a hex only if absolutely necessary, with a comment
+explaining the choice.
 
 ```tsx
-// ❌ Color.CorePurple500  /  Color.PrimaryPurple  /  #3F48FD
-// ✅ Color.TextActive  /  Color.BackgroundButtonPrimary
+// ❌ color: ${Color.TextPrimary};  /  Color.CorePurple500  /  #3F48FD  /  theme.color.text.primary
+// ✅ color: ${({ theme }) => semanticColor(theme, 'FgPrimary', Color.TextPrimary)};
 ```
 
-| Need | Use |
-|------|-----|
-| Text | `Color.TextPrimary` / `TextSecondary` / `TextInverse` / `TextActive` / `TextDanger` / `TextDisabled` |
-| Page / card background | `Color.BackgroundPrimary` / `BackgroundSecondary` |
-| Borders | `Color.BorderHairline` / `BorderDivider` / `BorderFocus` |
-| Buttons | `Color.BackgroundButtonPrimary` (and Default / Danger + Hover variants) |
-| Inputs | `Color.BackgroundInputDefault` / `BorderInputDefault` |
-| Charts | `ChartingColors.Sequential` or `.Categorical` |
-
-```tsx
-const Panel = styled.div`
-  background-color: ${Color.BackgroundPrimary};
-  border: 1px solid ${Color.BorderDivider};
-  color: ${Color.TextPrimary};
+### Use a PDS component before you pick any token
 
-  &:hover {
-    background-color: ${Color.BackgroundSecondary};
-  }
-`;
-```
+PDS components are what we want people to use: they already carry the right tokens for light and
+dark mode. The most common mistake is painting tokens over a custom component instead. A custom frame
+sets its own background, so dark mode never reaches it.
 
-### Core
+**Is there a PDS component that does this job one-for-one?** If so, use it, and delete the
+hand-written color overrides — PDS already carries the right tokens. Check [COMPONENTS.md](COMPONENTS.md)
+first. For styling that has no component of its own, use the PDS mixins: `inputMixin`
+(`@persona/design-system/mixins/input`) for field chrome such as filter triggers, and
+`semanticScrollbar` (`@persona/design-system/mixins/scrollbar`) for scrollbars.
 
-Each core color has shades from 50 (lightest) to 1100 (darkest):
+Same job, same token: a list of pressable rows hovers like a menu, a card looks like a `Tile`, a
+filter trigger looks like an input, a pill looks like an outline `Button`.
 
-```tsx
-// Purple
-Color.CorePurple50     // #F4F5FF (lightest)
-Color.CorePurple100
-Color.CorePurple500    // Mid-range purple
-Color.CorePurple700
-Color.CorePurple1100   // #010334 (darkest)
-
-// Other core colors follow same pattern:
-// CoreRed, CoreOrange, CoreYellow, CoreGreen, CoreTeal, CoreBlue, CoreSlate
-```
+### If a custom component is needed, use the same semantic tokens as its PDS equivalent uses
 
-### Primary
+**No exact match?** Keep the custom component and give it **the same tokens its PDS equivalent
+uses**. Don't swap in a component that would lose behavior. Examples:
 
-```tsx
-Color.PrimaryBlack    // #000000
-Color.PrimaryWhite    // #FFFFFF
-Color.PrimaryPurple   // #3F48FD (brand purple)
-Color.PrimaryRed      // #F04B38
-Color.PrimaryOrange   // #F59602
-Color.PrimaryYellow   // #DFFD2F
-Color.PrimaryGreen    // #41D49D
-Color.PrimaryTeal     // #36EBFD
-Color.PrimaryBlue     // #2B7FFD
-```
+- A two-step wizard modal can't be rebuilt on PDS `Modal` without changing how it works, so it keeps
+  its frame and uses PDS Modal tokens: `SurfacePrimary` card, `BorderSubtle` header and footer
+  dividers, `FgPrimary` title.
+- A select that has to show greyed-out (disabled) options keeps its component and uses PDS Select
+  tokens.
 
-### Background
+### Picking semantic tokens for custom components
 
-```tsx
-Color.BackgroundPrimary      // #FFFFFF (main background)
-Color.BackgroundSecondary    // #F5F5F6
-
-// Button backgrounds
-Color.BackgroundButtonDefault
-Color.BackgroundButtonDefaultHover
-Color.BackgroundButtonPrimary
-Color.BackgroundButtonPrimaryHover
-Color.BackgroundButtonDanger
-Color.BackgroundButtonDangerHover
-
-// Input backgrounds
-Color.BackgroundInputDefault
-Color.BackgroundInputActive
-Color.BackgroundInputDisabled
-
-// Label backgrounds
-Color.BackgroundLabelGrey
-Color.BackgroundLabelPurple
-Color.BackgroundLabelRed
-Color.BackgroundLabelGreen
-// ... and more label variants
-
-// Status indicator backgrounds
-Color.BackgroundStatusIndicatorSuccess
-Color.BackgroundStatusIndicatorWarning
-Color.BackgroundStatusIndicatorCritical
-Color.BackgroundStatusIndicatorFeature
-```
+For whatever is still custom, decide what the color is doing: text, surface, border, button, field,
+tinted message, status or scrollbar. Pick that family from the tables below, then the role inside it.
 
-### Text
+For hover, pressed and disabled, use the token with that suffix (`ActionPrimaryHover`,
+`InputSurfaceDisabled`). The state is part of the name. When a color must look the same in light and
+dark, use the Static version.
 
-```tsx
-Color.TextPrimary      // #313131 (main text)
-Color.TextSecondary    // #707070 (secondary text)
-Color.TextInverse      // #FFFFFF (text on dark backgrounds)
-Color.TextActive       // #3F48FD (active/link text)
-Color.TextDanger       // #B81F0E (error text)
-Color.TextDisabled     // #BDBDBD (disabled text)
-
-// Status indicator text colors
-Color.TextStatusIndicatorSuccess
-Color.TextStatusIndicatorWarning
-Color.TextStatusIndicatorCritical
-```
+Read tokens with `semanticColor(theme, 'Token', fallback)` from
+`@persona/design-system/lib/semanticColor`. The fallback is what themes without semantic tokens show:
+pass today's color so those themes look exactly as before. If the token's light value differs from
+today's color, list the old and new color so a person can approve it (for example `FgDisabled` is
+#BDBDBD where the old value was #CCCCCC). Don't read `theme.semantic` directly; the
+`no-direct-theme-semantic` lint rule rejects it. For a declaration that should exist only under
+semantic theming, use `semanticOnly((tokens) => …)` from the same module.
 
-### Border
+For a wash or a disabled fade, combine the color with an opacity token using `withAlpha` from
+`@persona/design-system/lib/color` (see Opacity below for which token, and how each behaves in light
+and dark). A wash reads two tokens, so get them with `semanticTokens(theme)`, branch on it, and
+return today's color when the theme has no semantic tokens. For focus, use `BorderFocus` through
+`@persona/design-system/mixins/focus`.
 
 ```tsx
-Color.BorderHairline     // #F1F1F2 (subtle border)
-Color.BorderDivider      // #E2E2E3 (section divider)
-Color.BorderFocus        // #2B7FFD (focus state)
-
-// Input borders
-Color.BorderInputDefault
-Color.BorderInputHover
-Color.BorderInputActive
-Color.BorderInputWarning
-Color.BorderInputDanger
-Color.BorderInputDisabled
-
-// Icon borders
-Color.BorderIconPrimary
-Color.BorderIconSecondary
-Color.BorderIconActive
-Color.BorderIconSuccess
-Color.BorderIconWarning
-Color.BorderIconDanger
+import { semanticColor, semanticTokens } from '@persona/design-system/lib/semanticColor';
+import { withAlpha } from '@persona/design-system/lib/color';
+
+const Row = styled.button<{ $selected: boolean }>`
+  color: ${({ theme }) => semanticColor(theme, 'FgPrimary', Color.TextPrimary)};
+  background: ${({ theme, $selected }) => {
+    if (!$selected) return 'transparent';
+    const tokens = semanticTokens(theme);
+    // A wash combines two tokens, so branch and keep today's color for themes without them.
+    return tokens ? withAlpha(tokens.SurfaceAccent, tokens.Opacity25) : Color.CorePurple50;
+  }};
+
+  &:hover {
+    background: ${({ theme }) => semanticColor(theme, 'SurfaceHover', Color.BackgroundSecondary)};
+  }
+`;
 ```
 
+#### Text and icons — Fg*
+
+Use Fg* for text, and for icons that sit with that text. An icon takes the same token as its label.
+
+| When | Token |
+|---|---|
+| The main thing to read: body, names, values, form labels, neutral button labels | `FgPrimary` |
+| Names and labels in navigation: nav items, environment names, the chevron beside them | `FgPrimary` |
+| A standalone icon button or chevron | `FgPrimary` |
+| Supporting text: descriptions, timestamps, placeholders, helper text, empty-state messages, counts on a pill | `FgSecondary` |
+| The quietest text: small chrome labels that should recede further than secondary | `FgTertiary` |
+| The control is unavailable | `FgDisabled` (fallback `Color.TextDisabled`) |
+| A link, the current item, a selected pill's label, or any text that should read as the brand color | `FgAccent` |
+| That brand text on hover | `FgAccentHover` |
+| That brand text while pressed | `FgAccentActive` |
+| Brand purple that must look the same in both themes | `FgAccentStatic` |
+| A label on a primary or danger button, which flips with the button fill | `FgInverse` |
+| A mark or label that must stay white in both themes (a check, text on a saturated fill) | `FgInverseStatic` |
+| Text that must stay dark in both themes, because the fill behind it doesn't flip | `FgPrimaryStatic` |
+| Secondary text that must stay the same slate in both themes | `FgSecondaryStatic` |
+| An error, a required marker, or destructive text at rest | `FgDanger1` |
+| Danger text on a danger fill, or danger text in its emphasized state | `FgDanger2` |
+| Caution text | `FgWarning1` |
+| Warning text on a warning fill | `FgWarning2` |
+| Text or an icon on a success, info, attention, feature, or miscellaneous fill | `FgSuccess`, `FgInfo`, `FgHighlight`, `FgFeature`, `FgMisc` |
+
+`FgDanger1` and `FgWarning1` are the tokens the PDS form error and warning messages use. Use them for
+any error or warning text so it matches.
+
+`FgPrimary` follows the theme: dark on a light surface, light on a dark one. Use a Static foreground
+when the fill behind the text doesn't flip or stays mid-tone, so the text doesn't flip without it.
+
+**Icons.**
+- An icon inside a button takes the button's label color. Remove any hard-coded override so it
+  follows the button at rest, on hover and when disabled.
+- An icon on its own (nav icon, chevron, toggle) gets an explicit token. "No color" means browser
+  black.
+- Nav icons use the same token as their label: `FgPrimary` at rest, `FgAccent` on the current item.
+- Dots and marks that carry meaning (availability, status) keep their own Status or Feedback token.
+
+#### Surfaces — Surface*
+
+Use Surface* for neutral layout fills. A colored message, tag or status uses Feedback* or Status*
+instead.
+
+| When | Token |
+|---|---|
+| The canvas behind the screen | `SurfacePage` |
+| The main surface content sits on: a card, a modal (PDS `Modal` is an elevated `Card` painted `SurfacePrimary`), a panel, page header, list | `SurfacePrimary` |
+| A region nested inside a primary surface: a header band, a well, a grouped area | `SurfaceSecondary` |
+| An empty-state box inside a table, list or form, never a fixed white | `SurfaceSecondary` |
+| A further step of nesting, stronger than secondary | `SurfaceTertiary` |
+| A faint separation from the parent surface | `SurfaceSubtle` |
+| A sunken well: a track, a recessed slot, an inset editor | `SurfaceInset` |
+| A neutral row or item under the pointer: menu items, list options, any list of pressable rows in a panel | `SurfaceHover` |
+| A layer that floats *over* other content and isn't a modal: a dropdown or combobox list, popover, filter popover, tooltip, floating panel, floating action bar | `SurfaceElevated` |
+| A brand-tinted selection or emphasis on a neutral surface | `SurfaceAccent` |
+| That tint, held to the same color in both themes | `SurfaceAccentStatic` |
+
+`SurfaceHover` is a temporary state. A region that is always slightly different from the body is
+`SurfaceSecondary` or `SurfaceSubtle`, even if it looks similar. On a row, copy only the menu's hover
+color, not the whole menu style.
+
+A selected row or menu item is `SurfaceAccent` with `Opacity25` (`withAlpha`): solid in light mode,
+a 25% wash in dark (see Opacity below).
+
+#### Borders — Border*
+
+There are two kinds of divider, matching the PDS source:
+
+| When | Token |
+|---|---|
+| A divider that's part of a component: modal header and footer dividers, a tab bar's baseline, a card section's top rule, a select footer, a slider track, a quiet internal hairline | `BorderSubtle` (fallback `Color.BorderDivider`) |
+| A rule between content items: table rows, menu sections, list items in a panel, the foot of a page header, and the edge of a card (as Tile does) | `BorderDivider` |
+| The resting outline of a control that isn't a text field (outline button, pill) | `BorderDefault` |
+| That outline while hovered | `BorderHover` |
+| Keyboard focus | `BorderFocus` |
+| A brand-colored mark of selection: an active tab underline, a selected pill's border, a selected edge | `BorderAccent` |
+| A field or region in an error state | `BorderDanger` |
+| A field or region in a warning state | `BorderWarning` |
+
+Field chrome uses `InputBorder*`. `BorderDanger` and `BorderWarning` are the error and warning
+strokes on those fields; the message beside them is `FgDanger1` or `FgWarning1`.
+
+**Floating layers have no added border.** Menus, flyouts, popovers, the side-nav flyout and modals
+stand apart through their surface and shadow. Don't add an edge, and remove one a custom style had.
+Keep a border only when the PDS component draws one itself or the design calls for it.
+
+**Fixed divider colors.** The fixed `Color.BorderHairline` and `Color.BorderDivider` become the
+`BorderDivider` token, or `BorderSubtle` for a divider inside a component. The old color with the
+same name isn't the token; it doesn't flip.
+
+#### Scrollbars
+
+Every scroll container gets a themed scrollbar; the browser default stays light in dark mode. Use the
+`semanticScrollbar` mixin (`@persona/design-system/mixins/scrollbar`) rather than writing it by hand.
+It paints:
+
+| Part | Token |
+|---|---|
+| Thumb at rest | `BorderDefault` |
+| Thumb on hover | `BorderHover` |
+| Track | transparent, so the surface shows through |
+
+This applies to navs, panels, dropdown lists, modal bodies and footers alike.
+
+#### Buttons and pressable chrome — Action*
+
+Use Action* for the fill of a control that's meant to be pressed. The surface behind the button stays
+a Surface* token. Prefer PDS `Button` with the matching `variant` to hand-painting these.
+
+| When | Rest | Hover | Pressed | Label |
+|---|---|---|---|---|
+| The main action | `ActionPrimary` | `ActionPrimaryHover` | `ActionPrimaryActive` | `FgInverse` |
+| A destructive action | `ActionDanger` | `ActionDangerHover` | `ActionDangerActive` | `FgInverse` |
+| A low-emphasis action | `ActionNeutral` | `ActionNeutralHover` | `ActionNeutralActive` | `FgPrimary` |
+| An action drawn as an outline | transparent, stroke `BorderDefault` | `ActionOutlineHover` | `ActionOutlineActive` | `FgPrimary` (count `FgSecondary`, disabled `FgDisabled`) |
+| A button on a dark or brand-filled background | `ActionInverse` | `ActionInverseHover` | `ActionInverseActive` | `FgPrimaryStatic` |
+| Small quick actions on a list item (mark read, archive) | `ActionInverse` | `ActionInverseHover` | `ActionInverseActive` | `FgPrimaryStatic` |
+| A brand tint on a pressable row, short of a full primary button | `ActionAccent` | | | `FgPrimary` or `FgAccent` |
+
+Panel-level text actions with icons (acting on every item in the panel) use default button styling;
+the icon follows the label.
+
+**Disabled:**
+- A destructive button uses `ActionDangerDisabled` when that state needs its own color; otherwise
+  fade the danger fill with `Opacity65`.
+- Disabled neutral and inverse fills fade with `Opacity65`.
+- Disabled labels on neutral actions are `FgDisabled`.
+- Disabled labels on primary and danger actions stay `FgInverse`, and the whole control fades with
+  `Opacity65`.
+
+#### Fields and choice controls — Input*
+
+Use Input* for the fill and stroke of anything a person types into or toggles. For a custom field or
+filter trigger, apply `inputMixin` (`@persona/design-system/mixins/input`) rather than setting these
+by hand.
+
+| When | Fill | Border |
+|---|---|---|
+| A text field at rest | `InputSurfaceDefault` | `InputBorderDefault` |
+| That field on hover | `InputSurfaceHover` | `InputBorderHover` |
+| That field when disabled | `InputSurfaceDisabled` | `InputBorderDisabled` |
+| A search box built into a modal or panel header, separated by a divider rather than a field outline | transparent in every state | none |
+| A checkbox, radio, or switch that needs a heavier resting stroke than a text field | `InputSurfaceDefault` | `InputBorderStrong` |
+| That choice control on hover | `InputSurfaceHover` | `InputBorderHoverStrong` |
+| The on or checked state | `InputSurfaceAccent` | `InputBorderAccent` |
+| The on state on hover | `InputSurfaceAccentHover` | `InputSurfaceAccentHover` (intentional; PDS Checkbox and Radio do the same) |
+| The on state when disabled | `InputSurfaceAccentDisabled` | `InputBorderDisabled` |
+| A knob or mark that must stay white | `InputSurfaceInverseStatic` | |
+
+Field text:
+- Text inside a field is `FgPrimary`.
+- Placeholder text is `FgSecondary`.
+- Disabled text is `FgDisabled`.
+- The check on a selected control is `FgInverseStatic`.
+
+Fade a disabled field or choice control with `Opacity65`.
+
+#### Tinted messages, chips and stickers — Feedback*
+
+Use Feedback* when the color categorizes or emphasizes content: a banner, a tag, a sticker, a
+highlight. Pick the hue for the meaning and the number for the strength.
+
+| Hue | When | Tokens that exist |
+|---|---|---|
+| Accent | Brand emphasis | `FeedbackAccent1`–`3`, `FeedbackAccent1Static` |
+| Info | Neutral information | `FeedbackInfo1`–`3` |
+| Success | A positive outcome | `FeedbackSuccess1`–`3` |
+| Warning | Caution | `FeedbackWarning1`–`3` |
+| Highlight | Attention, a spotlight | `FeedbackHighlight1`–`2` |
+| Danger | An error or a destructive category | `FeedbackDanger1`–`4` |
+| Misc | A category that needs its own hue, distinct from brand and from success or danger | `FeedbackMisc1`–`2` |
+| Neutral | No extra meaning; a grey chip or wash | `FeedbackNeutral1`–`5`, `FeedbackNeutral2Static` |
+| Neutral Inverse | A light chip that should read as the inverse of the surrounding neutral | `FeedbackNeutralInverse` |
+
+| Step | When |
+|---|---|
+| 1 | A quiet wash behind content. Text on it is `FgPrimary`. |
+| 2 | The default fill for a tag or sticker. |
+| 3 | A stronger fill, or the hover of a step-2 chip. |
+| 4 and 5 (Danger 4, Neutral 4–5 only) | The strongest fills. Text on these is `FgInverse` or `FgInverseStatic`. |
+
+Hover on a chip moves one step stronger in the same hue. Text on a mid-tone chip (step 2 and most of
+step 3) is `FgPrimaryStatic`, so it stays dark in both themes. Text on a neutral chip that follows the
+theme is `FgPrimary`.
+
+A Static feedback token is a step locked to one color. Use it when the chip sits on a surface that
+also doesn't flip, or when the highlight must match in both themes.
+
+When you fix an icon color in a component, check that the fix doesn't reach chips or stickers that
+share the same icon style.
+
+#### Status — Status*
+
+Use Status* when the color reports state: a record's outcome, a toast about something that just
+happened, the filled part of a progress indicator. Pair the fill with the foreground of the same
+meaning.
+
+| Meaning | Fill | Foreground |
+|---|---|---|
+| No particular outcome | `StatusNeutral` | `FgPrimary` |
+| Success | `StatusSuccess1`–`3` | `FgSuccess` |
+| Information, in progress, a notice | `StatusInfo1`–`3` | `FgInfo` |
+| Caution | `StatusWarning` | `FgWarning1` on an icon or helper, `FgWarning2` on a filled status |
+| Attention | `StatusHighlight` | `FgHighlight` |
+| Failure or a blocking error | `StatusDanger1Static`, `StatusDanger2`–`4` | `FgDanger1` at rest, `FgDanger2` on the fill |
+| A product or feature callout | `StatusFeature` | `FgFeature` |
+| A status that needs the extra hue | `StatusMisc` | `FgMisc` |
+
+**Pill backgrounds are always faded.** A filled status pill takes its Status fill through `withAlpha`
+with an opacity token, exactly as PDS `StatusIndicator` does; only `StatusNeutral` is used solid.
+Without the fade, a pale fill and its pale foreground lose contrast in dark mode. The pairs are in
+the status-pill recipe under Common recipes.
+
+Solid Status colors are for:
+- **Toast fills:** a low step across the whole toast (`StatusSuccess1`, `StatusInfo1`,
+  `StatusDanger2`), with `FgPrimaryStatic` for the message.
+- **Marks and progress:** the high end (`StatusSuccess3`, `StatusInfo3`, `StatusDanger4`) for a
+  progress fill, mark or icon that has to read as that hue on its own.
+
+`StatusDanger1Static` is the light danger wash that stays light in both themes. The other danger
+steps change with the theme.
+
+A status with no fill keeps `FgPrimary` for the label and uses the meaning's foreground token for the
+icon alone.
+
+#### Opacity
+
+Opacity tokens are percentages (`CssPercentage`), not colors. Use them to tint a semantic color or to
+fade a disabled control. Don't use them in place of a hover or active token that already exists.
+
+| Token | Light | Dark | When |
+|---|---|---|---|
+| `Opacity65` | 65% | 65% | A disabled control, or a disabled label on its own fill. Behaves the same in both modes |
+| `Opacity25` | 100% | 25% | Menu and selection states: a selected menu item, list option, row or pill (`SurfaceAccent` + `Opacity25`), a danger menu item on hover (`FeedbackDanger1` + `Opacity25`); also info and mild emphasis, including the info and feature status pills |
+| `Opacity15` | 100% | 15% | A light wash of success, warning, danger, or attention: banners, and the success, warning, danger, attention and misc status pills |
+
+Only `Opacity65` is a real fade in both modes. `Opacity15` and `Opacity25` take effect only in dark
+mode, where they turn a saturated fill into a wash so text on it keeps its contrast. In light mode
+they resolve to `100%`, so the underlying token shows solid — the light tokens are already pale
+(PX-1838 tracks whether that should change). Pick the base token for how it should look in light
+mode, and the opacity for how it should calm down in dark.
+
+Menus: a neutral row on hover is `SurfaceHover` with no opacity; the selected or active row is
+`SurfaceAccent` at `Opacity25`. PDS `Menu`, `ListBox`, `Select` and the menu item mixin all do this.
+
+Pass a percentage fallback (`semanticColor(theme, 'Opacity65', '65%')`). For the CSS `opacity`
+property, convert with `opacityOf` from `@persona/design-system/lib/color`.
+
+### Common recipes
+
+**A section of a page.**
+- Canvas `SurfacePage`; the section `SurfacePrimary`.
+- Title and values `FgPrimary`; descriptions `FgSecondary`.
+- Sections separated by `BorderDivider`.
+- A nested header strip inside the section is `SurfaceSecondary`.
+
+**A card or metric tile.** Use or match PDS `Tile`:
+- fill `SurfacePrimary`, border `BorderDivider`
+- title and value `FgPrimary`, small labels `FgSecondary`
+- never the fixed `Color.BorderHairline`
+
+**A modal.** Use PDS `Modal`. It is an elevated `Card` with:
+- `SurfacePrimary` fill and a shadow, no outer border
+- `BorderSubtle` header divider (none when it has tabs) and footer divider
+- title `Heading size='sm'` in `FgPrimary`
+- close button `Button variant='text'`
+- footer buttons right-aligned in the footer slot
+- body scrolling with `semanticScrollbar`
+
+If the modal can't move to PDS `Modal` (a multi-step wizard, for example), keep its frame, apply
+exactly those tokens to this one modal, and leave the shared frame alone. Menus inside it portal into
+the modal's container.
+
+**A menu, dropdown, popover or flyout.**
+- `SurfaceElevated`, no added border.
+- Rows hover with `SurfaceHover`; the selected row follows the selected-row recipe.
+- Themed scrollbar.
+
+**A command palette or search modal.**
+- Like a modal, with no border.
+- The search box is transparent with no border, separated from results by a `BorderDivider` rule.
+- If pointing at a result already selects it, the selected style is enough; don't add a separate
+  hover color.
+
+**A side panel.**
+- `SurfaceElevated` panel with no outer border.
+- `BorderDivider` under the header and between items; items hover with `SurfaceHover`.
+- Per-item quick actions use the inverse button; panel-level actions use default button styling.
+- Themed scrollbar.
+
+**Navigation.**
+- Labels, icons, environment names and chevrons `FgPrimary`.
+- Current item: `FgAccent` on the label and icon, with `SurfaceAccent` at `Opacity25`.
+- Hover `SurfaceHover`; flyouts follow the menu recipe.
+- Themed scrollbar. Status dots keep their own color.
+
+**A timeline.**
+- Rail line `BorderDivider`.
+- The event-type filter is a PDS `Combobox`.
+
+**A primary action and a quiet one.**
+- Primary: `ActionPrimary` and `FgInverse`.
+- Quiet: `ActionNeutral` and `FgPrimary`, or an outline (`BorderDefault`, then `ActionOutlineHover` /
+  `ActionOutlineActive`).
+
+**A form.**
+- Use PDS inputs.
+- Label `FgPrimary`, field `InputSurfaceDefault` and `InputBorderDefault`, placeholder `FgSecondary`.
+- An error swaps the border to `BorderDanger` and the message to `FgDanger1`.
+- A warning uses `BorderWarning` and `FgWarning1`.
+
+**A banner.**
+- Feedback at step 1, with the hue chosen from the meaning (info, success, warning, danger), with
+  `Opacity15` or `Opacity25` (the step shows solid in light, as a wash in dark).
+- Text stays `FgPrimary`.
+
+**A tag or sticker.**
+- Feedback at step 2 in the category's hue.
+- Text `FgPrimaryStatic` on a colored tag, `FgPrimary` on a neutral one.
+
+**A status pill (a record's state).** Use or match PDS `StatusIndicator`: the Status fill faded with
+`withAlpha`, and the meaning's foreground for the label and icon.
+
+| Meaning | Background | Label and icon |
+|---|---|---|
+| Neutral | `StatusNeutral` (solid) | `FgPrimary` |
+| Success | `StatusSuccess2` + `Opacity15` | `FgSuccess` |
+| Danger | `StatusDanger3` + `Opacity15` | `FgDanger2` |
+| Warning | `StatusWarning` + `Opacity15` | `FgWarning2` |
+| Attention | `StatusHighlight` + `Opacity15` | `FgHighlight` |
+| Misc | `StatusMisc` + `Opacity15` | `FgMisc` |
+| Info | `StatusInfo2` + `Opacity25` | `FgInfo` |
+| Feature | `StatusFeature` + `Opacity25` | `FgFeature` |
+
+The fade shows only in dark mode; in light mode the opacity tokens are `100%`, so the fill is solid
+(see Opacity).
+
+**A selected row.**
+- Hover is `SurfaceHover`.
+- Selected is `SurfaceAccent` at `Opacity25`, with `FgAccent` on the label or `BorderAccent`
+  on the edge that marks the selection.
+
+**An empty state.**
+- Fill `SurfaceSecondary`, message `FgSecondary`.
+- When the empty state comes from a shared component, set it at your call site; don't change the
+  shared component without listing every screen it reaches.
+
+**Help text on a label.**
+- Use PDS `TextUnderlineTooltip` (dashed underline) on the label instead of a separate help icon.
+- Write plain, left-aligned text with no bullets, in a "Label: text" form.
+- Near the side nav or a screen edge, use `align="start"` so it isn't clipped.
+
+### Before you hand it over
+
+- PDS components are used wherever a one-for-one match exists. Where none exists, the component uses
+  its PDS equivalent's tokens.
+- Every changed color uses a semantic token, with today's color as the fallback. No raw palette
+  (`Color.Core*`, `Color.Primary*`, `Color.Text*` …) or old theme value is the painted color.
+- No new borders or outlines, except the frame a newly adopted PDS component brings (listed as a
+  visible change).
+- Nothing is left on a fixed palette color or the browser default: icons, chevrons, bare buttons,
+  inputs, scrollbars, dividers, empty states, hover.
+- Icons inside buttons have no color overrides.
+- Dark-mode contrast was checked for text, icons and disabled states.
+- Any visible light-mode change is listed with its old and new color, so it can be approved.
+- Shared components that changed are listed with every screen they reach. Mirrored code wasn't
+  edited.
+- Tests cover light, dark, and a theme without semantic tokens; washes are checked with their opacity.
+- If copy moved or changed, the translation files were regenerated, not hand-edited, and existing
+  translations carried over.
+- One area per PR, with no unrelated changes.
+
+### Palette (fallbacks only)
+
+`Color` from `@persona/design-tokens` is the fixed palette. Its only place in feature code is the
+`semanticColor` fallback (today's color, so themes without semantic tokens are unchanged), and
+`withAlpha` / `opaqueOver` inputs.
+
+| Group | Names |
+|---|---|
+| Core shades, 50 (lightest) to 1100 (darkest) | `CorePurple*`, `CoreRed*`, `CoreOrange*`, `CoreYellow*`, `CoreGreen*`, `CoreTeal*`, `CoreBlue*`, `CoreSlate*` (e.g. `CorePurple50` #F4F5FF … `CorePurple1100` #010334) |
+| Brand primaries | `PrimaryBlack`, `PrimaryWhite`, `PrimaryPurple` (#3F48FD), `PrimaryRed`, `PrimaryOrange`, `PrimaryYellow`, `PrimaryGreen`, `PrimaryTeal`, `PrimaryBlue` |
+| Text | `TextPrimary` (#313131), `TextSecondary` (#707070), `TextInverse`, `TextActive` (#3F48FD), `TextDanger` (#B81F0E), `TextDisabled` (#BDBDBD), `TextStatusIndicator*` |
+| Backgrounds | `BackgroundPrimary` (#FFFFFF), `BackgroundSecondary` (#F5F5F6), `BackgroundButton*`, `BackgroundInput*`, `BackgroundLabel*`, `BackgroundStatusIndicator*` |
+| Borders | `BorderHairline` (#F1F1F2), `BorderDivider` (#E2E2E3), `BorderFocus` (#2B7FFD), `BorderInput*`, `BorderIcon*` |
+
+Several names share one hex (`CorePurple600`, `PrimaryPurple`, `BackgroundButtonPrimary` and
+`TextActive` are all #3F48FD); use the one that matches what the code painted before.
+
 ## Spacing
 
 `Spacing` is an enum of fixed gaps from `0` to `56px` (`Spacing[0]`–`Spacing[9]`).