<!-- Protocore Design System — Callout -->
# Callout

- **Category:** Cards (`cards`)
- **Slug:** `cards/callout`
- **Status:** stable
- **Platforms:** web, mobile
- **Import:** `import { Callout } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/cards/callout

> A tone-tinted note with a 2px left rule — the one place a note earns color, over an optional mono uppercase title.

## When to use it

Use **Callout** for a *contained* note inside page or document flow — a caveat next to a config field, a gotcha in a doc section. Use **Banner** for a *full-bleed, page-level* announcement that spans the layout (often dismissible). Use **Badge** for a *tiny inline status pill* attached to another element, not a paragraph of copy. Callout is the mid-weight option: bigger than a Badge, more local than a Banner. Remember the differentiation contract — a Callout tint is a status signal, never a decorative accent, and `--pds-accent` (brand green) is never a Callout tone.

## Mobile (React Native)

**Preview.** `@protocore/pds-mobile` ships the React Native sibling of **Callout**. It mirrors the web API where React Native allows; the package is a **preview** with no device-level QA yet, so pin it and expect small changes.

Import it from the mobile package (not `@protocore/pds`), inside a `<PdsProvider>` — there is no stylesheet, so `style` (a `ViewStyle`) replaces `className` and every value comes from the theme:

```tsx
import { Callout } from "@protocore/pds-mobile";
```

**Parity with web.** A tone-tinted note with a 2dp left rule and an optional mono uppercase title.

- RN exposes only the single base tone colour, so the tint is derived (web uses per-tone `-bg` / `-fg` tokens).

```tsx
<Callout tone="info" title="Heads up">
  This region is in preview.
</Callout>
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | no | — | Callout body copy. |
| `className` | `string` | no | — | — |
| `style` | `CSSProperties` | no | — | — |
| `title` | `ReactNode` | no | — | Optional mono UPPERCASE title above the body. |
| `tone` | `enum` | no | `info` | Status tone — sets the tint background, the left rule and the title colour. |

## Examples

### Basics

A `tone` sets the tint background, the left rule, and the title color. The `title` is optional; body copy is children.

```tsx
import { Callout } from "@protocore/pds";

export default function CalloutBasics() {
  return (
    <Callout tone="info" title="Note">
      Decentralized Verifier Networks let each application choose its own security stack and
      confirmation thresholds, with no shared trust assumptions.
    </Callout>
  );
}
```

### Tones

Callout carries the five status tones — `success`, `warning`, `danger`, `info` (default), and `neutral`. Tone is the *only* color signal; keep the copy tone-appropriate.

```tsx
import { Callout } from "@protocore/pds";

export default function CalloutTones() {
  return (
    <div style={{ display: "grid", gap: 12 }}>
      <Callout tone="success" title="Deployed">
        Endpoint <code>vt-mainnet-07</code> is live and serving traffic.
      </Callout>
      <Callout tone="warning" title="Rate limit">
        You are within 10% of the 5,000 req/min quota for this API key.
      </Callout>
      <Callout tone="danger" title="Immutable">
        Endpoints cannot be paused or rolled back once deployed — design your routes accordingly.
      </Callout>
      <Callout tone="neutral">
        A plain, tone-neutral note carries the hairline rule without a title.
      </Callout>
    </div>
  );
}
```

## Usage

**Do**

- Match `tone` to the message: `danger` for irreversible actions, `warning` for limits, `success` for confirmations, `info` for neutral notes.
- Lead with a short mono `title` ("Note", "Caution", "Deployed") so the callout is scannable.
- Keep the body to a sentence or two — a Callout is a note, not a section.
- Use `neutral` when you want the boxed-note framing without a status claim.

**Don't**

- Don't use a Callout for a page-wide announcement — that's Banner.
- Don't pick a tone for decoration; `success` green must mean success, not "look here".
- Don't nest interactive flows (forms, multi-step actions) inside a Callout.
- Don't stack several differently-toned Callouts in a row; the color loses meaning.

## Accessibility

**Notes**

- Callout renders a static `<div>`; tone is conveyed by the tinted rule and the title text, never by color alone — always keep a text label so the meaning survives for color-blind and screen-reader users.
- For a note that appears in response to a live event, add `role="status"` (polite) or `role="alert"` (assertive) via the spread `...rest` props so assistive tech announces it.
- The tint palette meets contrast against its foreground token in both light and dark themes.

## Related

`card`, `banner`, `badge`, `tile`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/