# PromoLabel

> Slug: `promo-label` · Category: Display

## When to use
- Highlight promotional or value-oriented copy near a product, plan, or offer (e.g., "Limited time", "Save $200").
- Add a small inline emphasis flag with optional leading icon.
- Reinforce a CTA's value prop in marketing layouts.

## When NOT to use
- Status reporting (success, error, info) — use `StatusLabel`.
- Generic chip selection or filtering — use `Chips` or `FilterChip`.
- Long descriptive text — use a `Tidbit` or body copy.

## Variants & decision tree
- Default emphasis -> `variant="primary"` (default).
- Lower-emphasis token / muted styling -> `variant="secondary"`.
- Strong/loud emphasis (high-contrast) -> `variant="strong"`.
- Add a leading icon to reinforce meaning -> pass `icon` (SVG ReactNode); set `iconA11yLabel` if the icon carries meaning.

## States
- Inverse-aware (theme or `inverse` prop).
- Returns `null` when `text` is falsy.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`text`** | `ReactNode` | — | Visible label. |
| `icon` | `ReactNode` | — | Leading SVG icon. |
| `iconA11yLabel` | `string` | — | Accessible name for icon-only meaning. |
| `variant` | `'primary' \| 'secondary' \| 'strong'` | `'primary'` | Emphasis. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Extra class names. |

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

// Plain promotional flag
<PromoLabel text="Limited time" />

// With leading icon and strong emphasis
<PromoLabel
  variant="strong"
  text="Save $200"
  icon={<svg viewBox="0 0 24 24"><path d="M12 2l3 7h7l-5.5 4.5L18 22l-6-4-6 4 1.5-8.5L2 9h7z"/></svg>}
/>

// Secondary on inverse hero
<PromoLabel variant="secondary" text="New" inverse />
```

## Composition
- Place inside `Tile`, `BillCard`, `PromoBanner` content, or alongside a `Title` to call out value.
- Pair with `Button` / `LinkStyledAsButton` CTAs in plan-card layouts.

## Accessibility
- Renders a non-interactive `<div>`; not focusable.
- The label text is announced by screen readers as plain content.
- If the leading `icon` carries meaning that text doesn't repeat, give it an accessible name (the icon SVG itself should set `role="img"` + `aria-label`); `iconA11yLabel` is consumed for that purpose.

## Do / Don't
- Do: keep text short — single phrase or 2–3 words.
- Do: use `variant="strong"` sparingly; reserve for the loudest call-out per surface.
- Don't: use to communicate validation status — pick `StatusLabel`.
- Don't: stack many `PromoLabel`s next to one element; choose one focused message.
