Status

A small status label with a tone, an icon, and a page-language label, plus a legend of the site's status values.

Trust: Unreviewed
Examples
Not recorded
Drift
Not recorded
Last reviewer
No reviewer recorded

Why this level

  • No review is recorded for this page, so its evidence has not been checked by a reviewer.

3 minutes read

On this page

A status is a small label for the state of a thing: done, late, draft. Each tone has its own icon and text, so a reader never needs colour to tell them apart. Two directives use it: the ::status[text]{tone=positive} badge, and the ::status-legend, which lists the values your site maps.

Syntax

::status[Done]{tone=positive}

::status{value=shipped}

::status-legend

Status options

Option Type Default What it does
tone positive, caution, negative, neutral, or info neutral The colour and icon. An unknown value is neutral.
label string empty The text shown when the directive has no body.
value string none A data value looked up in theme.options.status.values; it supplies the tone and the label.

The text between the brackets is the label. Both directives are block-level: put each on its own line, with a blank line before and after. A value wins over tone and over the body text.

Status legend options

Option Type Default What it does
values comma-separated values every mapped value The subset to list, in this order. Blank, repeated, and unmapped values are skipped.

Theme options

The site maps its own data values under theme.options.status.values. The theme ships no defaults, so a site with no map renders no legend and shows every value as written, in neutral.

Show all
theme:
  options:
    status:
      values:
        shipped:
          tone: positive
          label:
            en: Shipped
            fa: ارسال شد
          description: The work is done and released.
        pending:
          tone: caution
          label: Pending
          description: Waiting on a review.
        blocked:
          tone: negative
          label:
            en: Blocked
            fa: مسدود
          description: Something must change first.
        draft:
          tone: info
          label: Draft
Key What it does
tone One of the five tones. Missing or unknown is neutral.
label A string for every language, or a table from language code to text. The page's language is tried first, then its primary subtag (fa-IR reads fa), then English. With no label for the language, the raw value is shown.
description The same two forms. The legend shows it after the badge; a value without one shows the badge alone.

Example

Every tone, with its icon and its text label:

Done Check Late Archived Info
::status[Done]{tone=positive}

::status[Check]{tone=caution}

::status[Late]{tone=negative}

::status[Archived]{tone=neutral}

::status[Info]{tone=info}

A mapped value takes both its tone and its label from the site's options, so the same word reads in the page's language:

Shipped Pending Blocked Draft
::status{value=shipped}

::status{value=pending}

::status{value=blocked}

::status{value=draft}

An unmapped value is not an error: it shows as written, in neutral.

in-review

The legend lists every mapped value in map order, each as the badge above followed by its description:

  • ShippedThe work is done and released.
  • PendingWaiting on a review.
  • BlockedSomething must change first.
  • Draft
::status-legend

Pass values to choose and order a subset:

  • BlockedSomething must change first.
  • ShippedThe work is done and released.
::status-legend{values="blocked, shipped"}

Without JavaScript

Both directives render at build time to plain HTML and CSS. The icon is inline SVG, marked aria-hidden, and the label is real text, so a reader without JavaScript sees exactly the same badge and legend. Nothing is fetched, toggled, or remembered in the browser.

Notes

  • The badge is a label, not a link, and it is block-level. For a status inside a sentence, write the text and link the thing it names around it.
  • Do not use the single-colon :status form: the engine reads the two-colon leaf form only.
  • Colour is decoration: the icon and the text carry the meaning in every tone, including in forced-colours mode and in print.
  • The legend is a list, so a screen reader hears how many values the site defines. It renders nothing when the site maps no value.
  • Keep the mapped values short. They appear inside sentences as well as in the legend.
View Markdown

Use with an agent
View Markdown

Open in