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

- **Category:** Typography (`typography`)
- **Slug:** `typography/signal-count`
- **Status:** stable
- **Platforms:** web, mobile
- **Import:** `import { SignalCount } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/typography/signal-count

> THE green number — a single bracketed accent count with tabular figures, one per screen.

## A signature tell — and the accent budget

`SignalCount` is the third and most disciplined of the signature tells: **the one green number per screen.** It renders a bracketed count where only the digits take `--pds-accent` — the brand's reserved signal colour.

The accent is a strict budget. Per the differentiation contract, `--pds-accent` is *never* a button fill and *never* a status colour; it marks focus rings, selected nav markers, and this single live number. If green appears more than once on a screen, the budget is blown and the signal stops meaning anything. Treat a `SignalCount` like the one indicator light on a piece of hardware — there is exactly one, and it earns its glow.

## When to use it

Use `SignalCount` for the single most alive number on a view: open roles, networks live, messages per second, TVL. The optional `label` reads as muted mono beside the count.

For an *ordinal* — a step or card number — use `BracketIndex`, which is the same bracket shape but deliberately monochrome. For a *status* — active, degraded, error — use `Badge` with a tone tint; never encode status in the accent. And there should only ever be one `SignalCount` in a viewport; a second live number means one of them is really a `BracketIndex` or a plain `Text`.

## Mobile (React Native)

**Preview.** `@protocore/pds-mobile` ships the React Native sibling of **SignalCount**. 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 { SignalCount } from "@protocore/pds-mobile";
```

**Parity with web.** THE accent number — the single reserved-accent moment on a screen.

- The accent comes from `theme.colors.accent` (the RN stand-in for `--pds-accent`); like web, never use it as a button fill or a status.

```tsx
<SignalCount value={128} label="active" />
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` | no | — | — |
| `label` | `string` | no | — | Optional trailing label, rendered muted mono beside the count. |
| `size` | `enum` | no | `md` | Type scale: `sm` 11 · `md` 13 · `lg` 14. Default `md`. |
| `style` | `CSSProperties` | no | — | — |
| `value` | `ReactNode` | yes | — | The live number — the lone reserved-accent moment on a page. |

## Examples

### Basics

`SignalCount` wraps a live number in muted brackets and paints only the digits with `--pds-accent` — `[ 64 ] Networks Live`.

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

export default function SignalCountBasics() {
  return <SignalCount value={64} label="Networks Live" />;
}
```

### Sizes

Three mono steps: `sm` (11), `md` (13), `lg` (14). The label stays muted at every size so the number carries the emphasis.

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

export default function SignalCountSizes() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 14 }}>
      <SignalCount size="sm" value={12} label="Open Roles" />
      <SignalCount size="md" value={64} label="Networks Live" />
      <SignalCount size="lg" value="1.2M" label="Messages / Day" />
    </div>
  );
}
```

## Guidelines

**Do**

- Use exactly one `SignalCount` per screen — the lone accent moment.
- Reserve it for a genuinely live, load-bearing metric.
- Let the muted `label` describe the number; keep it a couple of words.
- Choose the `size` that matches the surrounding mono scale.

**Don't**

- Don't place two `SignalCount`s in the same viewport.
- Don't use the accent for status — that is a toned `Badge`.
- Don't use it for a static ordinal — that is `BracketIndex`.
- Don't wrap a stale or decorative number in it; the green implies liveness.

## Accessibility

**Notes**

- Renders an inline `span`; the brackets are `aria-hidden` so the value and label are announced cleanly.
- The accent digits meet contrast on the surface, but colour is not the only cue — the number and label always carry the meaning.
- Uses tabular figures so an updating count doesn't shift layout.

## Related

`bracket-index`, `eyebrow`, `badge`

---

© 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/