# Modes (Theme System)

Arrow's theme system has two axes: **inverse** (light vs dark surfaces) and **brand** (which T-Mobile family). Both are managed by `ArrowThemeProvider` and consumed automatically by every Arrow component.

## `ArrowThemeProvider`

```tsx
import { ArrowThemeProvider } from 'arrow-react-bootstrap';

<ArrowThemeProvider inverse={false} brand="tmobile">
  <App />
</ArrowThemeProvider>
```

| Prop | Type | Default | Effect |
|------|------|---------|--------|
| `inverse` | `boolean` | `false` | When `true`, descendant components render with dark surfaces. |
| `brand` | `'tmobile' \| 'metro' \| 'assurance'` | `'tmobile'` | Switches the brand accent (Magenta, Metro, Assurance). |

Internally the provider exposes `{ inverse, brand }` via React context. Components attach `data-inverse` / `data-brand` to their root, and Arrow's CSS targets those attributes — so the same component automatically restyles.

## Reading the theme — `useArrowTheme`

```tsx
import { useArrowTheme } from 'arrow-react-bootstrap';

function CustomBlock() {
  const { inverse, brand } = useArrowTheme();
  // Use only when authoring an Arrow-aware component yourself.
}
```

App-level code rarely needs this hook — every shipped component already consumes it.

## Patterns

### 1. App-wide theme

```tsx
<ArrowThemeProvider brand="tmobile">
  <App />
</ArrowThemeProvider>
```

### 2. Dark section by provider

Wrap a subtree to flip everything inside it.

```tsx
<ArrowThemeProvider inverse>
  <Header />        {/* dark surface, light text */}
  <HeroBanner />
</ArrowThemeProvider>
<MainContent />     {/* light surface again */}
```

### 3. Per-component `inverse`

Most components also accept their own `inverse?: boolean` prop. Pass it to override the surrounding context for a single component.

```tsx
{/* Light section, but this one button is inverse */}
<Button inverse variant="primary">Dark button on light section</Button>
```

When omitted, components inherit from the provider via `useArrowTheme`.

### 4. Brand override for a subtree

```tsx
<ArrowThemeProvider brand="metro">
  <MetroPromoSection />
</ArrowThemeProvider>
```

## Hard rules

- **NEVER write custom dark-mode CSS.** No `@media (prefers-color-scheme: dark)`, no `[data-theme="dark"]` selectors. Use `inverse`.
- **NEVER repaint components manually for inverse.** If a component looks wrong on a dark surface, you almost certainly forgot to set `inverse`.
- **One `ArrowThemeProvider` is enough at the root.** Nest only when you intentionally need to flip a subtree's `inverse` or `brand`.
- **Don't pass `inverse` to non-Arrow `<div>` elements.** It only does anything on Arrow components.
