Colour theme

Button

  • Primitives

  • buttons

One contract, two components. Button is the class and its four axes — emphasis, intent, size, pill — but the element decides which component you write: LinkButton renders an a and navigates, ActionButton renders a button and acts. They share Button.css, so the look can never be picked apart from the meaning. Intent belongs to actions alone.

Element

Same look, different element. A link goes somewhere; an action does something. The shared class is the reason there is no way to style an a as a button by hand — you pick the component, and the element follows.

Go to the map
astro
---
import LinkButton from "tsugite/Button/LinkButton.astro";
import ActionButton from "tsugite/Button/ActionButton.astro";
---
{/* One contract, two components. The element decides which: a LinkButton
    renders <a> and navigates, an ActionButton renders <button> and acts.
    They share .Button and every data-* axis, so the look cannot be chosen
    apart from the meaning. */}
<LinkButton href="/map">Go to the map</LinkButton>
<ActionButton>Save changes</ActionButton>

Emphasis

Emphasis ranks siblings: which of these buttons matters most. It says nothing about the surface underneath — that is the theme — and a primary button in a subtle section is the normal case. Tertiary is closed until it has a design: the recipe refuses it in development.

astro
---
import ActionButton from "tsugite/Button/ActionButton.astro";
---
{/* Emphasis ranks siblings against each other — it says nothing about the
    surface the button sits on (that is the theme). Tertiary is closed
    until it has a design: the recipe refuses it. */}
<ActionButton emphasis="primary">Primary</ActionButton>
<ActionButton emphasis="secondary">Secondary</ActionButton>

Intent — actions only

Destructive and success are things an action can be, not a link. The axis does not exist on a LinkButton: given an intent, it is refused in development rather than rendered without one. Intent writes the same slots emphasis writes, so hover, active and focus keep working; no theme sets the intent colours, so a destructive button is the same red on every band.

astro
---
import ActionButton from "tsugite/Button/ActionButton.astro";
---
{/* Intent exists only on ActionButton. An action can be destructive,
    risky or successful (ADR-0045); a link merely goes somewhere. A LinkButton given an intent is
    refused in development — the axis does not exist on <a>. */}
<ActionButton intent="neutral">Neutral</ActionButton>
<ActionButton intent="destructive">Delete</ActionButton>
<ActionButton intent="warning">Publish anyway</ActionButton>
<ActionButton intent="success">Confirm</ActionButton>

Size and pill

Three sizes, md by default, each resolving type and padding through label tokens. Pill is its own axis and the attribute is always written, so a button's shape is never implicit.

astro
---
import LinkButton from "tsugite/Button/LinkButton.astro";
---
{/* Three sizes, md by default. Pill is a second, independent axis: the
    attribute is always written (data-pill="false" | "true"), so the shape
    is never implicit. */}
<LinkButton href="#" size="sm">Small</LinkButton>
<LinkButton href="#" size="md">Medium</LinkButton>
<LinkButton href="#" size="lg">Large</LinkButton>
<LinkButton href="#" size="md" pill={true}>Pill</LinkButton>
<LinkButton href="#" size="md" pill={true} emphasis="secondary">Pill, secondary</LinkButton>

Icon

A button has two slots, start and end: iconStart and iconEnd reference the page sprite, drawn in the theme's icon set. Drop the text and the button is square — then the whole accessible name comes from aria-label or from a screen-reader affix, never both.

astro
---
import LinkButton from "tsugite/Button/LinkButton.astro";
import ActionButton from "tsugite/Button/ActionButton.astro";
---
{/* A button has two slots, start and end (ADR-0039). iconStart / iconEnd name an icon
    of the theme, drawn inline in the theme's icon set (ADR-0048); a name the theme does not
    have stops the build. Without text the button
    becomes icon-only and is square — then aria-label is the whole accessible name, and
    without one the button would not render at all. */}
<LinkButton href="#" iconEnd="mail">Contact us</LinkButton>
<LinkButton href="#" iconStart="calendar">Book a time</LinkButton>
<ActionButton iconEnd="icon-search" aria-label="Search" emphasis="secondary" />

Media

What is not an icon — a logo group, an avatar — goes in the start or end slot and keeps its own shape. Its block size is the icon's unless the project sets its own; like an icon, it never makes the button taller. A slot holds one thing: an icon or media.

astro
---
import ActionButton from "tsugite/Button/ActionButton.astro";
---
{/* Media in a slot (ADR-0039): what is not an icon — a logo group, an avatar — goes in the
    start or end slot and keeps its own shape; its block size is the icon's unless the
    project sets its own, and like an icon it never makes the button taller. */}
<ActionButton emphasis="secondary" iconEnd="icon-search" data-media-example>
  <svg slot="start" viewBox="0 0 54 24" aria-hidden="true">
    <g fill="currentColor" fill-opacity=".14" stroke="currentColor" stroke-opacity=".45">
      <circle cx="11" cy="12" r="10.5" /><circle cx="27" cy="12" r="10.5" /><circle cx="43" cy="12" r="10.5" />
    </g>
  </svg>
  Onboard your agent
</ActionButton>

The accessible name

The visible words stay in the name; screenReaderPrefix and screenReaderSuffix complete it before and after, in DOM order, as ScreenReaderText spans that take no room. A bare value needs both: visibly 3, announced as Page 3 of 12. An icon-only button may take its whole name from an affix instead of aria-label. Two names on one button — aria-label and an affix — are refused in development.

Read more about the exhibition
astro
---
import LinkButton from "tsugite/Button/LinkButton.astro";
import ActionButton from "tsugite/Button/ActionButton.astro";
---
{/* The visible words stay in the accessible name; a screen-reader affix completes it
    before or after, in DOM order. A bare value needs both: "Page 3 of 12". An icon-only
    button may take its whole name from an affix instead of aria-label — never both. */}
<LinkButton href="#" screenReaderSuffix=" about the exhibition">Read more</LinkButton>
<ActionButton emphasis="secondary" screenReaderPrefix="Page " screenReaderSuffix=" of 12">3</ActionButton>
<ActionButton emphasis="secondary" iconEnd="icon-search" screenReaderPrefix="Search" screenReaderSuffix=" the site" />

The ownership chain

The button reads its colours through a generated chain — custom ← surface ← theme ← ground — and never reads data-theme. A Theme steps into a theme, the theme fills the theme station, and the same markup renders three ways.

astro
---
import LinkButton from "tsugite/Button/LinkButton.astro";
import Theme from "tsugite/Theme/Theme.astro";
---
{/* The ownership chain. The button reads its colours through a generated chain —
    custom ← surface ← theme ← ground — and knows nothing about themes. A Theme steps into a
    theme, the theme fills the theme station. Same markup, three grounds: the page, then two
    themes. */}
<div class="ownership">
  <LinkButton href="#">Primary</LinkButton>
  <LinkButton href="#" emphasis="secondary">Secondary</LinkButton>
</div>
<Theme name="theme-2" class="ownership">
  <LinkButton href="#">Primary</LinkButton>
  <LinkButton href="#" emphasis="secondary">Secondary</LinkButton>
</Theme>
<Theme name="theme-1" class="ownership">
  <LinkButton href="#">Primary</LinkButton>
  <LinkButton href="#" emphasis="secondary">Secondary</LinkButton>
</Theme>

<style>
  /* Example chrome only: the air and the row are the example's, never the Theme's. */
  .ownership {
    display: flex;
    flex-wrap: wrap;
    gap: var(--size-sm);
    padding: var(--size-md);
    border-radius: 0.75rem;
  }
</style>

The empty rule

No text, no icon, no aria-label: nothing to click and nothing to announce, so the component renders nothing. An empty button tag never reaches the page.

astro
---
import ActionButton from "tsugite/Button/ActionButton.astro";
---
{/* The empty rule. No text, no icon, no aria-label: nothing to click and
    nothing to announce, so the component renders nothing at all rather
    than an empty <button>. Only the second one below reaches the DOM. */}
<ActionButton />
<ActionButton>Rendered</ActionButton>

Test bench

The button state map for an action in the two emphases that paint differently. Every emphasis, intent and content lives on the full-coverage page.

The state map

An action, neutral, in the two emphases that paint differently — primary fills, secondary outlines: one table per content — a label, a label and an icon, an icon alone — with sm, md and lg in every cell. Idle stands above the table; each state is alone on the diagonal and two states meet below it. What cannot happen is hatched with its reason; pairs not yet measured are marked.

Primary

Label

idle

hover

active

focus-visible

disabled

hover

active

a pointer press

focus-visible

reached by keyboard, pointed at

a held Space

disabled

? unmeasured

:hover on a disabled button differs by engine

? unmeasured

does any engine match :active on a disabled button?

unreachable

a disabled button takes no focus

hover + active + focus-visible

a held Space under the pointer

Label and an icon

idle

hover

active

focus-visible

disabled

hover

active

a pointer press

focus-visible

reached by keyboard, pointed at

a held Space

disabled

? unmeasured

:hover on a disabled button differs by engine

? unmeasured

does any engine match :active on a disabled button?

unreachable

a disabled button takes no focus

hover + active + focus-visible

a held Space under the pointer

Icon alone

idle

hover

active

focus-visible

disabled

hover

active

a pointer press

focus-visible

reached by keyboard, pointed at

a held Space

disabled

? unmeasured

:hover on a disabled button differs by engine

? unmeasured

does any engine match :active on a disabled button?

unreachable

a disabled button takes no focus

hover + active + focus-visible

a held Space under the pointer

Secondary

Label

idle

hover

active

focus-visible

disabled

hover

active

a pointer press

focus-visible

reached by keyboard, pointed at

a held Space

disabled

? unmeasured

:hover on a disabled button differs by engine

? unmeasured

does any engine match :active on a disabled button?

unreachable

a disabled button takes no focus

hover + active + focus-visible

a held Space under the pointer

Label and an icon

idle

hover

active

focus-visible

disabled

hover

active

a pointer press

focus-visible

reached by keyboard, pointed at

a held Space

disabled

? unmeasured

:hover on a disabled button differs by engine

? unmeasured

does any engine match :active on a disabled button?

unreachable

a disabled button takes no focus

hover + active + focus-visible

a held Space under the pointer

Icon alone

idle

hover

active

focus-visible

disabled

hover

active

a pointer press

focus-visible

reached by keyboard, pointed at

a held Space

disabled

? unmeasured

:hover on a disabled button differs by engine

? unmeasured

does any engine match :active on a disabled button?

unreachable

a disabled button takes no focus

hover + active + focus-visible

a held Space under the pointer