# status-pill — portfolio lifecycle-badge primitive

A small, mono, uppercase badge that sits under a record title to signal its
state. Five semantic variants, optionally driven from one JSON state-vocabulary
so you add a state once — not per row. Hosted at
`https://assets.gf.cx/status-pill/`.

Lifted from [home.gf.cx/returns](https://home.gf.cx/returns/), where every
order / return / repair row carries a state pill.

## Import

```html
<link rel="stylesheet" href="https://assets.gf.cx/status-pill/status-pill.css">
<script src="https://assets.gf.cx/status-pill/status-pill.js" defer></script>
```

The JS is optional — pure CSS works if you hand-pick the variant class.

## The five variants

| variant | colour | use |
|---|---|---|
| `.status-pill--neutral` (default) | accent green on faint tint | in-progress / informational |
| `.status-pill--alert` | gold on gold tint | needs attention (e.g. *delivered not received*) |
| `.status-pill--resolved` | white on accent green · ✓ | closed-good (e.g. *refund issued*) |
| `.status-pill--service` | white on accent green · 🔧 | serviced / returned — a *confirmation*, so it shares the resolved green; the 🔧 sets it apart from ✓ |
| `.status-pill--warning` | white on signal-orange · ⚠ | high-visibility warning / danger — the loud tier above alert (e.g. *recall · stop use*) |

A warning colour on a positive outcome reads wrong, so **service** (a
confirmation) wears the green and the loud orange is reserved for the **warning**
variant.

```html
<span class="status-pill status-pill--resolved">Resolved · refund issued · $401.74</span>
<span class="status-pill status-pill--service">Service complete · returned 1 Jun 2026</span>
<span class="status-pill status-pill--warning">Recall · stop use</span>
```

Icons (`✓`, `🔧`, `⚠`) are supplied by each variant's CSS `::before` — don't type them
into the label.

## Data-driven pattern (recommended)

Don't hand-style each pill. Tag it with a state key, keep **one** vocabulary on
the page, and let `status-pill.js` compose every pill at load:

```html
<!-- one vocabulary per page, keyed by data-state -->
<script type="application/json" data-status-pill>
{ "refund-issued":    { "label": "Resolved · refund issued", "variant": "resolved" },
  "service-complete": { "label": "Service complete",         "variant": "service" } }
</script>

<!-- pills carry only the key + a free-text detail -->
<span class="status-pill" data-state="refund-issued"
      data-detail="$401.74 · 20 Jun 2026"></span>
```

At load, every `.status-pill[data-state]` gets `.status-pill--<variant>` and its
text set to `label[ · detail]`. The server-rendered class/text is the **no-JS
fallback**. A starter vocabulary (the /returns/ lifecycle) ships at
[`states.example.json`](./states.example.json).

Add a new state in the JSON, never in per-row markup — that's the whole point.

## Design-system colours referenced

Variants map to colours **active in the portfolio palette**, each via a CSS
custom property with a hex fallback, so pills theme automatically on any surface
that defines the tokens and still render on bare HTML.

| token | hex | drives |
|---|---|---|
| `--accent` | `#2c4a3a` | neutral fg · resolved bg · service bg |
| `--gold` | `#b8862a` | alert |
| `--signal-orange` | `#f5871f` | warning / danger *(high-visibility)* |
| `--ink` / `--ink-soft` | `#1a1816` / `#5a544d` | text neutrals (inherited) |
| `--bg` / `--bg-warm` | `#f7f3ec` / `#ebe3d5` | surface grounds (inherited) |

Override per-surface like any other primitive:

```css
:root { --pill-orange: #e2700f; }  /* tune the warning colour on this surface */
```

Live swatch reference rendered on the [demo page](https://assets.gf.cx/status-pill/).

## Print

Pills flatten to a bordered, black-on-white box with the icon preserved.

## Cross-references

- In use: `home.gf.cx/returns/` — the originating surface (inline vocabulary;
  `_data/states.json` is the repo-side manifest, mirrored inline because the
  Pages `rest` deploy slice excludes `_data/`).
- `cards.css` — sibling primitive; same custom-property theming convention.

## Version

v0.1.0 · 2026-06-20 · first shipped at https://assets.gf.cx/status-pill/