---
title: Stage Card
description: Pipeline / kanban / roadmap stage card with intent-tinted border, count pill, and optional progress
visibility: guest
draft: false
---

# Stage Card

A column-header / stage primitive for kanban boards, sales pipelines, roadmap quarters, and workflow milestones. Renders an intent-tinted border, a faintly intent-tinted body, an optional item-count pill, and an optional completion bar — the pattern dashboards previously hand-rolled per column.

## Basic Usage

:::preview{title="Plain stage card"}
<x-wirekit::stage-card label="Backlog">
    <x-wirekit::card><x-wirekit::card.body>Draft onboarding email</x-wirekit::card.body></x-wirekit::card>
    <x-wirekit::card><x-wirekit::card.body>Spec the billing page</x-wirekit::card.body></x-wirekit::card>
</x-wirekit::stage-card>
:::

## Intents

The border and body tint pull from the matching design token. `neutral` is the default:

:::preview{title="Stage cards across intents"}
<x-wirekit::row gap="md" wrap>
    <x-wirekit::stage-card label="Backlog" intent="neutral" count="8" />
    <x-wirekit::stage-card label="In progress" intent="info" count="3" />
    <x-wirekit::stage-card label="In review" intent="warning" count="2" />
    <x-wirekit::stage-card label="Done" intent="success" count="14" />
    <x-wirekit::stage-card label="Blocked" intent="danger" count="1" />
</x-wirekit::row>
:::

## Count Pill

Pass `count` to show an item count in the header. The pill announces as `"N items"` to screen readers:

:::preview{title="Stage card with count"}
<x-wirekit::stage-card label="In progress" intent="info" count="12">
    <x-wirekit::card><x-wirekit::card.body>Implement the export endpoint</x-wirekit::card.body></x-wirekit::card>
</x-wirekit::stage-card>
:::

## Progress

Pass `progress` (0–100) to render a thin completion bar colored to match the stage intent:

:::preview{title="Stage card with progress"}
<x-wirekit::row gap="md" wrap>
    <x-wirekit::stage-card label="Q1 — Foundations" intent="success" :progress="100" />
    <x-wirekit::stage-card label="Q2 — Launch" intent="info" :progress="60" />
    <x-wirekit::stage-card label="Q3 — Scale" intent="neutral" :progress="15" />
</x-wirekit::row>
:::

## Pipeline Composition

Combine `count`, `progress`, and slotted items for a full pipeline stage:

:::preview{title="Full pipeline stage"}
<x-wirekit::stage-card label="Negotiation" intent="warning" count="4" :progress="45">
    <x-wirekit::card><x-wirekit::card.body>Acme Corp — $48k</x-wirekit::card.body></x-wirekit::card>
    <x-wirekit::card><x-wirekit::card.body>Globex — $22k</x-wirekit::card.body></x-wirekit::card>
</x-wirekit::stage-card>
:::

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string\|null` | `null` | Stage title rendered in the header. Also the `aria-label` of the group. |
| `intent` | `string` | `'neutral'` | Border + tint color: `primary` / `success` / `warning` / `danger` / `info` / `neutral`. |
| `count` | `int\|string\|null` | `null` | Item count rendered as a header pill (announced as `"N items"`). |
| `progress` | `int\|null` | `null` | Completion percentage `0..100`; renders a thin intent-colored bar. |
| `scope` | `string\|null` | `null` | Personalization scope key. |

## Slots

| Slot | Description |
|------|-------------|
| default | The stage's items (cards, rows, anything). Stacked vertically with a small gap. |

## Accessibility

- When `label` is set, the card is a `role="group"` with `aria-label="{label}"`, so the stage title is announced as the purpose of its grouped items.
- The count pill carries `aria-label="{count} items"` — the number is announced with its unit, not as a bare integer.
- The border color is decorative; the `label` text is the accessible name, so the stage is distinguishable without color perception.

## Keyboard Interaction

Stage Card is a presentational container — it has no interactive behavior of its own. Any interactive children (cards, buttons, links inside the default slot) own their own keyboard model.

## Pitfalls

- **Don't rely on the border color alone to convey the stage.** Always pass a `label` — color is a redundant cue, not the primary signal.
- **`progress` is a display value, not a control.** It mirrors a server-computed percentage; it isn't a slider. Pass an integer `0..100`.

## Design Tokens

| Token | Usage |
|-------|-------|
| `--color-wk-bg-elevated` | Body background (mixed with 6% of the intent color). |
| `--color-wk-border` | Card border. |
| `--radius-wk-lg` | Card corner radius. |
| `--color-wk-success` / `--color-wk-warning` / `--color-wk-danger` / `--color-wk-accent` / `--color-wk-text-muted` | Intent border + tint source. |

## Usage & Conventions

> **Prop conventions** — this component uses the shared semantic prop name `intent`. See [Prop naming conventions](/extending/prop-naming-conventions) for the canonical vocabulary, alias matrix, and decision tree.