Counter

A counter is a small number on or beside a control that says how many items wait there. It appears only when there is something to act on.

What it is

When to use it

Use a counter for a number someone can bring down by acting, such as unread notifications or the new applications waiting in a view.

Leave it off totals that only describe, such as the number of candidates on a board. Navigation pages carry no counters, since nothing on them waits to be read.

Anatomy

On an icon button the counter sits over the top end corner, so the icon stays whole. Beside a word it follows the word.

Applications

Height: 17 px
Minimum width: 17 px
Padding at the sides: 4 px; --space-1
Corner radius: 6 px; --radius-md
Numerals: 10.5 px, weight 700, tabular
Position on a button: 6 px above its top, 4 px past its end
Ring on a button: 2 px in the button's resting fill
Space after a label: 8 px; --space-2

Tones

Red is for items that need attention, such as unread notifications, and stays the same red in both themes. On a total that can wait it stops meaning attention. Blue says something arrived since the view was last opened, and turns gray once it is. Gray is a plain count.

Attention
New
Plain

Attention
New
Plain

Attention: red fill, white numerals; --badge-alert
New: blue tint, blue numerals; --track-tint
Plain: gray chip, gray numerals; --chip-fill

Numbers

Up to 999 the counter shows the exact number. From 1,000 it shows thousands with one decimal, rounded down so it does not claim more than there is: 1.9k for 1,999. From 10,000 it shows 10k+. At zero the counter disappears.

7
999
1,999
12,480

Accessibility

Screen readers skip the number itself. The control's name carries it together with what it counts: Applications, 12 in this view, new since you last opened it. A bare number read after a word tells the listener nothing.

The counter takes no focus of its own. The control it belongs to does. It grows in over 150 milliseconds, and appears without motion for anyone who has asked for reduced motion.

NextStatus

Counter

Shows how many items wait behind a control, as a small number the reader can bring down by acting.

Kind: component
Page: https://design.werklist.com/components/counter
Version: 2.1.2

When to use it

Unread notifications on a header button.
New applications in a view, beside its name.

When not to use it

Totals that only describe, such as the candidates on a board.
Navigation and marketing pages.
Zero or negative numbers.

Rules

A counter only for items the reader can bring down by acting.
The name of the control pairs the number with what it counts.
Red only for items that need attention, never for a total that can wait.

Anatomy

Height: 17 px
Minimum width: 17 px
Padding: 4 px at the sides (--space-1)
Radius: 6 px (--radius-md)
Numerals: 10.5 px, weight 700, tabular, line height 1
On a button: 6 px above the top edge of the button and 4 px past its end, with a 2 px ring in the resting fill of the button
Beside a label: 8 px after the label (--space-2)
Attention (--badge-alert, --badge-alert-ink)
New (--track-tint, --assign-accent)
Plain: on a --surface-control ground the fill is --surface-1 (--chip-fill, --chip-ink)

Variants

attention: Unread items that need action, in the same red in both themes.
new: Items that arrived since the reader last opened the view. It turns plain once the view is opened.
plain: A count the reader may act on without urgency.

States

hidden: the count is zero
shown: grows in over 150 ms, without motion under reduced motion (--duration-fast, --ease-standard)

Accessibility

The number is hidden from screen readers. The name of the control carries it with what it counts, such as Applications, 12 in this view, new since you last opened it.
No focus of its own.
A change of count updates the name of the control and is not announced.
In forced colors mode the numerals keep the text color inside a 1 px outline.

Content

0 hides the counter.
1 to 999 exact.
1,000 to 9,999 as thousands with one decimal, rounded down: 1.9k.
10,000 and above: 10k+.
Numbers take the same form in every language.

Tokens

--badge-alert
--badge-alert-ink
--track-tint
--assign-accent
--chip-fill
--chip-ink
--surface-1
--radius-md
--space-1
--space-2
--duration-fast
--ease-standard

JSON

{
  "title": "Counter",
  "path": "/components/counter",
  "url": "https://design.werklist.com/components/counter",
  "text": "https://design.werklist.com/agent/components/counter",
  "summary": "Shows how many items wait behind a control, such as unread notifications, as a small number.",
  "version": "2.1.2",
  "kind": "component",
  "name": "Counter",
  "purpose": "Shows how many items wait behind a control, as a small number the reader can bring down by acting.",
  "use": [
    "Unread notifications on a header button.",
    "New applications in a view, beside its name."
  ],
  "avoid": [
    "Totals that only describe, such as the candidates on a board.",
    "Navigation and marketing pages.",
    "Zero or negative numbers."
  ],
  "variants": [
    {
      "name": "attention",
      "use": "Unread items that need action, in the same red in both themes."
    },
    {
      "name": "new",
      "use": "Items that arrived since the reader last opened the view. It turns plain once the view is opened."
    },
    {
      "name": "plain",
      "use": "A count the reader may act on without urgency."
    }
  ],
  "anatomy": [
    {
      "part": "Height",
      "measure": "17 px"
    },
    {
      "part": "Minimum width",
      "measure": "17 px"
    },
    {
      "part": "Padding",
      "measure": "4 px at the sides",
      "token": "--space-1"
    },
    {
      "part": "Radius",
      "measure": "6 px",
      "token": "--radius-md"
    },
    {
      "part": "Numerals",
      "measure": "10.5 px, weight 700, tabular, line height 1"
    },
    {
      "part": "On a button",
      "measure": "6 px above the top edge of the button and 4 px past its end, with a 2 px ring in the resting fill of the button"
    },
    {
      "part": "Beside a label",
      "measure": "8 px after the label",
      "token": "--space-2"
    },
    {
      "part": "Attention",
      "token": "--badge-alert, --badge-alert-ink"
    },
    {
      "part": "New",
      "token": "--track-tint, --assign-accent"
    },
    {
      "part": "Plain",
      "measure": "on a --surface-control ground the fill is --surface-1",
      "token": "--chip-fill, --chip-ink"
    }
  ],
  "states": [
    {
      "name": "hidden",
      "change": "the count is zero"
    },
    {
      "name": "shown",
      "change": "grows in over 150 ms, without motion under reduced motion",
      "tokens": [
        "--duration-fast",
        "--ease-standard"
      ]
    }
  ],
  "accessibility": [
    "The number is hidden from screen readers. The name of the control carries it with what it counts, such as Applications, 12 in this view, new since you last opened it.",
    "No focus of its own.",
    "A change of count updates the name of the control and is not announced.",
    "In forced colors mode the numerals keep the text color inside a 1 px outline."
  ],
  "content": [
    "0 hides the counter.",
    "1 to 999 exact.",
    "1,000 to 9,999 as thousands with one decimal, rounded down: 1.9k.",
    "10,000 and above: 10k+.",
    "Numbers take the same form in every language."
  ],
  "tokens": [
    "--badge-alert",
    "--badge-alert-ink",
    "--track-tint",
    "--assign-accent",
    "--chip-fill",
    "--chip-ink",
    "--surface-1",
    "--radius-md",
    "--space-1",
    "--space-2",
    "--duration-fast",
    "--ease-standard"
  ],
  "rules": [
    "A counter only for items the reader can bring down by acting.",
    "The name of the control pairs the number with what it counts.",
    "Red only for items that need attention, never for a total that can wait."
  ]
}

Raw file: https://design.werklist.com/agent/components/counter