# Divider

> Slug: `divider` · Category: Display

## When to use
- Separate content sections horizontally (between paragraphs, list groups, card rows).
- Separate inline items vertically (e.g., metadata in a row).
- Add visual rhythm without introducing a heading or extra container.

## When NOT to use
- Decorative whitespace — use spacing utilities (`tdds:pt-*`, `tdds:mb-*`).
- Section heading separation when a `SectionHeader` already provides visual hierarchy.
- Border-only treatment of a card — use the card component's built-in border.

## Variants & decision tree
- Standard horizontal rule -> defaults.
- Thicker / accent rule for emphasis -> `variant="strong"`.
- Branded color rule -> `variant="branded"`.
- Vertical separator (e.g., between header items) -> `orientation="vertical"`. Wrap in a flex container with explicit height.

## States
- Inverse-aware (theme or `inverse` prop).
- Always renders `role="separator" aria-hidden="true"` — it is decorative.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direction. |
| `variant` | `'branded' \| 'strong'` | — | Emphasis variant. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Extra class names. |

## Usage examples
```tsx
import { Divider } from 'arrow-react-bootstrap';

// Horizontal between blocks
<p>Content above</p>
<Divider />
<p>Content below</p>

// Strong / branded variants
<Divider variant="strong" />
<Divider variant="branded" />

// Vertical separator in a flex row
<div style={{ display: 'flex', alignItems: 'center', height: 48, gap: 12 }}>
  <span>Left</span>
  <Divider orientation="vertical" />
  <span>Right</span>
</div>
```

## Composition
- Use beneath `SectionHeader` to set off content blocks.
- Use inside `ButtonTray` (built-in `hasDivider`) instead of stacking a manual one.
- Use inside list rows or metadata rows with vertical orientation.

## Accessibility
- Marked `aria-hidden="true"` — purely decorative.
- Do not rely on visual separation alone for meaning; ensure surrounding semantics convey structure.

## Do / Don't
- Do: keep dividers sparse — too many flatten visual rhythm.
- Do: pick `vertical` only when items are laid out in a row with consistent height.
- Don't: use as a section heading replacement — pair with text headings.
- Don't: animate or repurpose for non-separator use; choose a different element.
