Button
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.
---
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.
---
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.
---
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.
---
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.
---
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.
---
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.
---
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.
---
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.
---
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
a held Space under the pointer
Label and an icon
idle
hover + active + focus-visible
a held Space under the pointer
Icon alone
idle
hover + active + focus-visible
a held Space under the pointer
Secondary
Label
idle
hover + active + focus-visible
a held Space under the pointer
Label and an icon
idle
hover + active + focus-visible
a held Space under the pointer
Icon alone
idle
hover + active + focus-visible
a held Space under the pointer