Button

Preview

<EsaButton>Get started</EsaButton>

Variants

Eight semantic variants. ai maps to the copper AI-context palette; ghost is neutral and transparent.

<EsaButton variant="primary">Primary</EsaButton>
<EsaButton variant="secondary">Secondary</EsaButton>
<EsaButton variant="danger">Danger</EsaButton>
<EsaButton variant="success">Success</EsaButton>
<EsaButton variant="warning">Warning</EsaButton>
<EsaButton variant="info">Info</EsaButton>
<EsaButton variant="ai">AI</EsaButton>
<EsaButton variant="ghost">Ghost</EsaButton>

Appearances

The appearance axis is independent of variant — any variant renders as fill, outline, dashed, or soft. soft is a neutral surface with accent-colored text that fills on hover — variant="danger" appearance="soft" is the secondary-danger button.

<EsaButton variant="danger" appearance="fill">Fill</EsaButton>
<EsaButton variant="danger" appearance="outline">Outline</EsaButton>
<EsaButton variant="danger" appearance="dashed">Dashed</EsaButton>
<EsaButton variant="danger" appearance="soft">Soft</EsaButton>

Active (toggle)

Set active for a pressed/selected look (and aria-pressed) — the basis for toggle buttons.

<EsaButton appearance="outline">Default</EsaButton>
<EsaButton appearance="outline" active>Active</EsaButton>

Sizes

<EsaButton size="xs">Extra small</EsaButton>
<EsaButton size="sm">Small</EsaButton>
<EsaButton size="md">Medium</EsaButton>
<EsaButton size="lg">Large</EsaButton>

Icons

icon sits left of the label, iconRight sits right. They are independent props, not two settings of one, so a button can carry both. Reach for iconRight when the glyph is an affordance — where the action goes (arrow-right) or that it opens something (chevron-down) — and for icon when it labels what the action is. iconOnly drops the text and squares the box; it uses icon and ignores iconRight.

<EsaButton icon="plus">Leading</EsaButton>
<EsaButton iconRight="arrow-right">Continue</EsaButton>
<EsaButton appearance="outline" iconRight="chevron-down">Export</EsaButton>
<EsaButton icon="download" iconRight="chevron-down">Download</EsaButton>
<EsaButton iconOnly icon="plus" label="Add" />

States

Conditions the button is in, as opposed to what it is made of. Both are transient and both block interaction; loading also hides the label in place and suppresses either icon, so the width never jumps.

<EsaButton loading>Loading</EsaButton>
<EsaButton disabled>Disabled</EsaButton>
<EsaButton appearance="outline" active>Active</EsaButton>

Chrome — buttons that live on an app bar

Every other variant owns a color. That is exactly what makes them unusable on chrome: ghost resolves its text to --color-content-default, which is --color-gray-12 — the same token --color-background-default-knockout paints a dark app bar with. Gray-12 on gray-12 is a contrast ratio of 1:1.

chrome takes its color from context instead, so the containing App Bar decides it and the same markup works on a dark bar and a light one. The hover scrim and focus ring derive from currentColor for the same reason. This variant absorbed esa-icon-button (with iconOnly) and esa-icon-link (with a label) — both are deprecated shims now.

<EsaAppBar tone="brand-strong">
  <EsaButton variant="chrome" icon="trees" iconRight="chevron-down">Mitigation work</EsaButton>
  <EsaButton variant="chrome" current href="/reporting" icon="trending-up">Reporting</EsaButton>
  <EsaButton slot="end" variant="chrome" iconOnly icon="search" label="Search" />
</EsaAppBar>

API

Any other attribute (onclick, id, name, data-*, aria-*) is forwarded verbatim to the native element, so plain-JS callers can wire a handler or grab it by id.

Accessibility

• Renders a native <button> — keyboard and screen-reader behavior come for free.
• Visible focus ring via --focus-ring-* tokens (2px, offset).
• active sets aria-pressed (a toggle); current sets aria-current (a nav position). They are separate props because they are separate claims.
• iconOnly requires label. This is checked at build time and warns rather than failing the type — the label is a slot, so a boolean flag cannot make a sibling prop mandatory. Passing aria-label directly also satisfies it.
• variant="chrome" derives its focus ring from currentColor rather than --focus-ring-color, so the ring stays visible on a dark app bar.
• loading keeps the label in the DOM (visually hidden) so width doesn't jump and the name persists.
• warning fill uses dark text for contrast on the amber background.

Theming surface

Every public token this component reads, extracted from its source at build time, split by blast radius: the hooks that belong to this component, then the shared and system tokens it consumes alongside everything else. The Resolves to column walks each token's real lineage — component → semantic → primitive → raw value — so you can see exactly where re-pointing it lands. A spoke re-skins by overriding these in its theme-<slug>.css; component internals are never edited. No hook for what you need? File it with /request-lego.

Type roles it names

This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.

Wired to this component

No other component reads these — re-point them and esa-button is the only thing that moves.

Shared tokens it reads

Owned by a family or by the semantic layer. Still overridable — but scope the override (esa-foo { --form-border-color: … }) unless you mean to move everything that reads it. Reach says what else that is.