# Composition — Surfaces

A **surface** is a visual container that elevates content above the page background. Arrow surfaces fall into five families: inline cards, selectable cards, overlay dialogs, transient toasts, and inline notice bars. Pick the surface that matches the content's persistence (always-there vs. dismissible), interruption level (informational vs. blocking), and placement (inline vs. overlay).

## Surface families

| Surface | Components | Persistence | Placement | Use for |
|---|---|---|---|---|
| Card | `DisclosureCard`, `DisclosureCardSecondary`, `BillCard` | Persistent | Inline | Linked content, summaries, navigation tiles |
| Selectable | `Tile`, `StyledRadioGroup` | Persistent | Inline | Choices in a form (plans, options, colors) |
| Overlay | `Modal`, `FullPageInterruption` | Transient | On top of page | Confirmations, blocking flows, full-screen messages |
| Toast | `Snackbar` | Transient | Floating | Brief feedback after an action ("Saved", "Removed") |
| Inline alert | `NoticeBar` | Persistent (until dismissed) | Inline | Announcements, errors, system messages |

## Choosing a surface

Use this decision flow:

1. **Does the user need to act before continuing?** → `Modal` (or `FullPageInterruption` for full-screen)
2. **Is this confirmation feedback after an action?** → `Snackbar` (auto-dismisses)
3. **Is this a system message that lives on the page?** → `NoticeBar`
4. **Is this content the user can navigate to or open?** → `DisclosureCard` (or `BillCard` for billing-specific summaries)
5. **Is this a choice within a form?** → `Tile` or `StyledRadioGroup`

## NoticeBar variants

`NoticeBar` covers most inline messaging. The `variant` controls the icon, color, and ARIA role.

| Variant | Auto icon + `role="alert"` | When to use |
|---|---|---|
| `announcement` | No | Neutral, informational updates |
| `brand` | No | Promotional or branded content |
| `caution` | Yes | Warnings the user should notice |
| `error` | Yes | Failures the user must address |
| `positive` | Yes | Success confirmations on the page |

```tsx
<NoticeBar
  variant="error"
  title="Payment failed"
  body="Your card was declined. Please update your payment method."
  linkLabel="Update payment"
  href="/payments"
  isDismissable
/>
```

## Elevation rules

Surfaces stack from the page upward: page background → cards → notice bars → toasts → modals → full-page interruption.

- **Do not nest surfaces of equal elevation.** A card inside a card looks like a bug. If you need grouping inside a card, use `Divider` or a `tdds:row` with spacing — not another card.
- **Modals own the top.** Never place another modal-level surface (full-page interruption, second modal) on top unless the design system explicitly supports it.
- **Toasts float, but only one at a time.** Stack messages by replacing the current Snackbar, not stacking multiple.
- **Inline alerts live in the document flow.** Place a NoticeBar where the user is acting (top of the form for form errors, top of the page for system errors), not in a floating overlay.

## Inverse mode

Every surface accepts `inverse` and flips its colors automatically — no custom dark CSS. Set `inverse` either on `<ArrowThemeProvider>` (whole subtree) or on the surface component (per-instance).

```tsx
{/* Whole section dark */}
<ArrowThemeProvider inverse>
  <DisclosureCard tag="New" headline="Dark card" supportingText="…" href="/x" />
</ArrowThemeProvider>

{/* Just one card dark */}
<DisclosureCard inverse tag="New" headline="Dark card" supportingText="…" href="/x" />
```

When a section is `inverse`, surfaces inside use their inverse tokens; foreground content automatically picks up the inverse text and border colors. See `foundations/color.md` for the full surface token list.

## Surface checklist

- One purpose per surface — do not put a Modal-level decision inside a card
- Cards link or contain content; they don't host critical actions on their own
- Modals always have a clear close path (`closeAction` or a Cancel button)
- Snackbars are short, action-confirming, and auto-dismiss; if it needs an action, use a NoticeBar
- Never nest cards inside cards
- Never use raw `<div>` with custom box-shadow as a surface — use the components above
