---
title: Variants & Intents
description: Cross-component reference for color/severity props across the WireKit component library
visibility: guest
draft: false
---

# Variants & Intents

WireKit components communicate color, severity, or brand intent through one of two prop shapes. This page is the single source of truth for which prop name and which allowed values belong to each component — useful when copy-pasting between components and you hit a "is `primary` valid here?" moment.

## Canonical Set

Every WireKit component that exposes a color prop accepts the **same six canonical values**:

```text
primary | neutral | success | warning | danger | info
```

The names map onto the `VariantResolver::INTENTS` constant in PHP (`src/VariantResolver.php`), and they map onto the design tokens in `dist/wirekit.css`:

| Value | Token | Reads as |
|-------|-------|----------|
| `primary` | `--color-wk-accent` | brand emphasis, the call-to-action color |
| `neutral` | `--color-wk-bg-muted` / `--color-wk-text-muted` | quiet, non-emphasized |
| `success` | `--color-wk-success` | positive outcome (saved, completed, validated) |
| `warning` | `--color-wk-warning` | careful, reversible action ahead |
| `danger` | `--color-wk-danger` | destructive or error state |
| `info` | aliased to `--color-wk-accent` | informational; visual synonym of `primary` |

> **Note on `info` and `primary`:** WireKit uses a single brand token (`--color-wk-accent`) for both informational and brand-emphasis surfaces — they render identically. Use whichever name expresses your intent semantically; switching between them is purely stylistic.

## Per-Component Reference

Two prop shapes are in use:

- `intent` + `surface` (orthogonal: color × visual style) — used by `button`, `badge`. `message` uses `intent` alone (single soft-tinted bubble surface).
- `variant` (combined name + style in one prop) — used by `alert`, `callout`, `progress`, plus the legacy shorthand on `button` and `badge`

| Component | Prop | Allowed values | Notes |
|-----------|------|----------------|-------|
| `<x-wirekit::button>` | `intent` | primary, neutral, success, warning, danger, info | Modern API. Pair with `surface` for visual style. |
| `<x-wirekit::button>` | `surface` | filled, outline, soft, ghost, link | Pair with `intent`. |
| `<x-wirekit::button>` | `variant` (legacy) | primary, secondary, outline, ghost, danger, link | Back-compat shorthand. New code should prefer `intent` + `surface`. |
| `<x-wirekit::badge>` | `intent` | primary, neutral, success, warning, danger, info | Modern API. Pair with `surface`. |
| `<x-wirekit::badge>` | `surface` | filled, outline, soft, ghost | Pair with `intent`. |
| `<x-wirekit::badge>` | `variant` (legacy) | primary, success, warning, danger, info, neutral | Back-compat shorthand. |
| `<x-wirekit::message>` | `intent` | primary, neutral, success, warning, danger, info | Bubble background tint. `primary` and `info` render identically. |
| `<x-wirekit::alert>` | `variant` | primary, neutral, success, warning, danger, info | `primary` is a visual synonym of `info`; `neutral` is a quiet gray treatment for non-severity-bearing notices. |
| `<x-wirekit::callout>` | `variant` | primary, neutral, success, warning, danger, info | Same set + semantics as alert. Visually denser (15% vs 10% bg tint). |
| `<x-wirekit::progress>` | `variant` | primary, accent, success, warning, danger | `primary` is the canonical name; `accent` is a back-compat alias for the historical default. No `info`/`neutral` (a progress bar without semantic color uses the brand fill). |

## Choosing Between `intent` and `variant`

The two prop shapes overlap; both work on `button` and `badge`:

```blade
{{-- Modern: orthogonal intent × surface --}}
<x-wirekit::button intent="primary" surface="filled">Save</x-wirekit::button>

{{-- Legacy: combined shorthand --}}
<x-wirekit::button intent="primary">Save</x-wirekit::button>
```

The two render identically. New code should prefer `intent` + `surface` because it composes better — you can change "filled to soft" without touching color, or "primary to danger" without touching surface style.

`alert`, `callout`, and `progress` only expose `variant` because they don't have a meaningful surface dimension (an alert is always "the alert surface", not filled-vs-outline).

## Common Pitfalls

**Pitfall 1 — every component accepts the same six canonical values.** `<message>`, `<alert>`, `<callout>`, `<progress>`, and the other intent-carrying components all consume `primary` / `neutral` / `success` / `warning` / `danger` / `info`. Reach for the same value name across components — you won't be surprised by a per-component enum gap.

**Pitfall 2 — `variant="accent"` on `<progress>` is legacy.** The canonical name is `primary`. `accent` continues to work to avoid breaking existing developer code, but new code should use `primary`.

**Pitfall 3 — `severity` semantics on `alert`/`callout`.** Historically, `alert` and `callout` were "severity-only" (info / success / warning / danger). The expansion to include `primary` and `neutral` adds two non-severity treatments: `primary` is a brand-emphasis variant of `info`, and `neutral` is a quiet gray treatment for notices that aren't carrying any severity weight. If you find yourself wanting `severity="info"`, just write `variant="info"` — the prop name is `variant`, not `severity`.

**Pitfall 4 — the four status names also exist as icon aliases.** `info`, `success`, `warning`, and `danger` are *both* canonical intent values on components like `<x-wirekit::badge>` AND semantic icon aliases on `<x-wirekit::icon>`. They are intentionally paired — `<x-wirekit::icon name="info">` resolves to `heroicon-m-information-circle` (or its sibling in the active preset), the same icon you would conventionally place inside `<x-wirekit::badge intent="info">`. The shared keyword is a feature, not a collision: status surfaces and their leading icons read identically across the catalog. See the [icon semantic-alias reference](components/icon.md#status-and-feedback) for the full mapping.

## See Also

- [`<x-wirekit::button>`](components/button.md) — `intent` + `surface` reference implementation
- [`<x-wirekit::badge>`](components/badge.md) — same prop shape as button
- [`<x-wirekit::message>`](components/message.md) — chat bubble with intent tint
- [`<x-wirekit::alert>`](components/alert.md) — variant-based notice
- [`<x-wirekit::callout>`](components/callout.md) — variant-based denser notice
- [`<x-wirekit::progress>`](components/progress.md) — variant-based progress fill
- [Design Tokens](/theming/design-tokens) — full color-token reference
- [Theming](/theming) — setup guide and theme presets