# Button

Built from the Figma-derived specification. Appearance is three axes —
`intention` × `context` × `emphasis` — bound straight to the token groups.
Geometry never varies: padding, the 40px minimums and the 1px border are
identical on every combination and every state.

Live at `/button-demo` — every combination, every state, on all three surfaces.

## Provenance

Every value comes from `github.com/samiamdesigns/pd-xrpl-developer-docs`:
`components/button.md` (the axes and the reasoning), `components/button.json`
(values resolved per mode), `components/button-examples.md` (the acceptance
checklist), plus `accessibility/focus-indicators.md`,
`implementation/icons-that-inherit-colour.md` and
`implementation/font-stacks.md`.

The colour matrix in `Button.scss` §2 was generated rather than transcribed and
verified back against `button.json`: all 270 values, both modes, no RGB
mismatch.

## API

```tsx
<Button>Get started</Button>

<Button intention="neutral" emphasis="standard">Learn more</Button>
<Button context="on-saturated">On a green block</Button>
<Button href="/docs" target="_blank">Read the docs</Button>
<Button iconEnd={<XrplArrowInternalLinkIcon />}>Read more</Button>
<Button loading>Submitting…</Button>
```

| Prop | Values | Default |
|---|---|---|
| `intention` | `brand` · `neutral` | `brand` |
| `context` | `on-theme` · `on-inverse` · `on-saturated` | `on-theme` |
| `emphasis` | `strong` · `standard` · `subtle` | `strong` |
| `loading` | boolean — `aria-busy`, activation suppressed, indicator shown | `false` |
| `inactive` | boolean — `aria-disabled`, **stays in the tab order** | `false` |
| `disabled` | boolean — native `disabled`, leaves the tab order | `false` |
| `href` / `target` | renders an `<a>` | — |
| `iconStart` / `iconEnd` | decorative, `aria-hidden` — either slot omitted renders no icon and reserves no space | — |

### `context` is the axis to get right

Each context is measured against a different backdrop, so choosing the wrong one
is the likeliest way to produce a button that looks plausible and fails
contrast. It also drives the focus-ring colour, and **nothing will tell you if
that is wrong** — a button that takes `context="on-inverse"` for its paint and
leaves the ring at its default renders perfectly.

### `neutral` + `on-saturated` does not compile

There are no tokens for it. The props are a discriminated union, so that
combination is a type error rather than a runtime surprise.

### Two `strong` buttons must not share a container

Emphasis is what says which action is primary. No checker catches this — a row
of identical `strong` buttons is contrast-clean and still wrong.

## States

Six states, three appearances. `hover`/`pressed`/`loading` resolve
byte-identically and `inactive` == `rest`, in all 15 combinations, in both
modes.

| Appearance | States |
|---|---|
| Resting | `rest`, `inactive` |
| Engaged | `hover`, `pressed`, `loading` |
| Disabled | `disabled` — its own group |

They stay separate code paths, because what distinguishes them is behaviour:

| | ARIA | tab order | activates |
|---|---|---|---|
| `loading` | `aria-busy` | in | no |
| `inactive` | `aria-disabled` | **in** | no |
| `disabled` | native `disabled` | **out** | no |

Collapsing `inactive` into `disabled` removes it from the tab order, and a
screen-reader user can then no longer find it.

**`disabled` is chosen by context alone** — not by intention, not by emphasis.
Emphasis only selects the shape: `strong` keeps fill and border, `standard`
drops the fill, `subtle` drops both.

## Anchor paint

`href` renders an `<a>`, so every bare `a` rule on the site applies to it —
Bootstrap's, the theme's, and any container styling its own anchors.
`Button.scss` §5 out-specifies them with a doubled class,
`a.bds-btn.bds-btn:link` and the other four link pseudo-classes.

**Do not collapse those into `:is()`.** PurgeCSS drops a rule when the argument
to `:is()` or `:where()` is a pseudo-class list or a `:not()` chain, so the tidy
form compiles, works in `realm develop`, and vanishes from the production bundle
— leaving anchor buttons painted as links. A plain selector argument is fine,
which is why `:where(html.dark)` in §4 survives. §5 is also deliberately
unlayered, since everything above it sits in `@layer bds-btn.*`.

## Not from the token set

- **The background rise** — a `::before` scaling from `bottom center`. The spec
  says hover swaps the whole triplet; the rise is only *how* the fill arrives.
- **The animated arrow**, with the motion inside the icon's own viewBox so the
  button's geometry never changes on hover.
- Motion values: 150ms, `cubic-bezier(0.98, 0.12, 0.12, 0.98)`.

## Deliberate deviations from the spec

| Deviation | Why |
|---|---|
| `intention` is optional | `button.md`'s printed union marks it required, which would reject `<Button>Get started</Button>` — the zero-prop default its own examples show. `button.json` records `"default": "brand"`. **Reported upstream.** |
| Loader glyph is `LoaderIcon` | The spec's glyph is an explicit placeholder and asks us to pick one and report back. **This is the choice to report.** |
| The loader slows under reduced motion rather than stopping | Freezing it removes the only signal that anything is happening. `aria-busy` covers assistive technology; nothing covers a sighted user watching a motionless spinner. |
| Alpha comes from `_colors.scss`, not `button.json` | The JSON rounds alpha to 2dp; `_colors.scss` carries the generated 8-digit Radix value the tokens are built from. 57 of 270 values differ by up to 1.2/255 of alpha. No RGB channel differs anywhere. |

## Where the colours come from

**Every colour in the palette is a variable from `styles/_colors.scss`** — not
one hex literal in the map. `_colors.scss` already carries the generated Radix
scales the tokens are built from, so binding the variables is shorter and truer
than copying numbers, and a palette change propagates on its own.

The pairs double as documentation: `($sage-12, $sage-dark-12)` reads as "step 12
of the neutral scale, per mode", and the on-inverse groups visibly swap them.

Three exceptions, commented in the file: the focus ring's `#111111` and
`#000000` come from `mode-color.focus-indicator.*`, a token family with no
counterpart in any scale the site carries. White binds `$white`.

To change a colour, edit the map in §2 — one `@each` loop emits all 30 rules.
To re-derive it, re-resolve `button.json`; if `button.md` and `button.json`
disagree, **neither wins**, re-resolve from the token set.

## Traps

- **`line-height: 1` is a ratio, not `1px`.** `button.md` reversed this on
  2026-08-17; converting it is the documented trap.
- **`on-inverse` is not a mode-swap of its base group.** 104 of 108 values
  survive that shortcut and 4 border values do not, so it is emitted literally.
- **PurgeCSS.** The group/emphasis/context classes are composed from props at
  runtime and emitted from a Sass loop, so they appear as literals nowhere.
  `postcss.config.cjs` safelists `/^bds-btn/` and `/^bds-icon/`; without them
  the production build silently strips the component.
- **`:where(html.dark)` in §4 is load-bearing.** A bare `html.dark` selector
  outranks the state swaps and leaves disabled buttons with their resting fill
  in dark mode only.