Skip to main content
WireKit
Copy for LLM

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:

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:

{{-- 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 for the full mapping.

See Also