action — wyrd.component.button

Button

Action primitive that emits one canonical press event from pointer, keyboard, and assistive activation.

Install @wyrd-company/react or the Flutter package and use it directly — your DESIGN.md does the styling.

catalog/contracts/button.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: Button  tag: wyrd-button  package: wyrd.component.button  title: Button  summary: Action primitive that emits one canonical press event from pointer, keyboard, and assistive activation.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: action  composition: multi-slot  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: variant      type:        kind: enum        values:          - primary          - secondary          - ghost          - danger      required: false      default: primary      reflects: true      serializable: true      summary: Visual and semantic action emphasis.    - name: is-disabled      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Prevents activation and exposes disabled platform semantics.    - name: is-loading      type:        kind: boolean      required: false      default: false      reflects: true      serializable: true      summary: Shows pending action state while preserving dimensions and suppressing duplicate activation.  slots:    - name: label      content: true      required: true      cardinality: exactly-one      accepts:        - text        - node      summary: Primary visible label and accessible-name source.    - name: leading-icon      required: false      cardinality: zero-or-one      accepts:        - icon      summary: Optional icon before the label in inline flow.    - name: trailing-icon      required: false      cardinality: zero-or-one      accepts:        - icon      summary: Optional icon after the label in inline flow.  events:    - name: press      payload:        source:          kind: enum          values:            - pointer            - keyboard            - assistive        action:          kind: action-ref      bubbles: true      composed: true      cancelable: true      summary: Canonical activation event emitted once per accepted activation.  states:    - name: default      source: platform      summary: Idle enabled state.    - name: hover      source: interaction      summary: Pointer hover state on hover-capable devices.    - name: focus-visible      source: platform      summary: Keyboard-visible focus state.    - name: pressed      source: interaction      summary: Active press state.    - name: disabled      source: property      summary: Disabled state derived from is-disabled.    - name: loading      source: property      summary: Pending state with a visible activity indicator derived from is-loading.  parts:    - name: root      summary: Interactive platform control root.      slots:        - label        - leading-icon        - trailing-icon    - name: label      summary: Label content container.      slots:        - label    - name: icon      summary: Icon slot containers.      slots:        - leading-icon        - trailing-icon    - name: loading-indicator      summary: Non-color-only indeterminate activity indicator shown before the stable label while loading.  tokens:    primary:      background: color.primary      background-hover: color.primary-hover      background-pressed: color.primary-pressed      foreground: color.on-primary    secondary:      background: color.secondary      foreground: color.on-secondary    ghost:      background: transparent      foreground: color.primary    danger:      background: color.error      foreground: color.on-error    disabled:      background: color.disabled      foreground: color.on-disabled    radius: rounded.md    padding-x: spacing.lg    padding-y: spacing.sm    gap: spacing.sm    label: typography.label-md    loading-indicator-size: spacing.md    loading-indicator-stroke-width: 2pxmessages: []obligations:  accessibility:    role: button    name: Label slot or aria-label provides the accessible name.    keyboard:      - Enter activates the button.      - Space activates the button.    semantics:      - Disabled state is exposed through native disabled semantics where the target has them.      - Loading state keeps the accessible name stable and prevents duplicate activation.      - The loading indicator is decorative because aria-busy exposes the pending state while the visible label remains the accessible name.  behavior:    model: stateless    interactions:      - Activation emits press when the button is enabled and not loading.      - Touch activation does not create hover state.      - Loading renders an indeterminate activity indicator before the unchanged label without changing the button's dimensions.      - Reduced-motion preferences replace continuous rotation with a static partial-ring indicator.    hostEffects:      - Dispatch activation event.      - Invoke action binding for SDUI when present.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact  sdui:    status: serializable    serializableProperties:      - variant      - is-disabled      - is-loading    serializableSlots:      - label      - leading-icon      - trailing-icon    eventBindings:      - press    notes: Press serializes as an action reference; executable callbacks stay target-local.examples:  - name: primary    state: default    properties:      variant: primary    slots:      label: Save changes  - name: loading    state: loading    properties:      variant: primary      is-loading: true    slots:      label: Save changes  - name: danger    state: default    properties:      variant: danger    slots:      label: Delete

Examples

Generated from the contract's examples block. Previews are the published @wyrd-company/react component, themed by the brand's role tokens — flip the site's light/dark toggle and they follow.

Code target React Flutter Applies to every example on component pages.

primary state: default

Usage

import { WyrdButton } from "@wyrd-company/react";

<WyrdButton variant="primary">
  Save changes
</WyrdButton>

// events: onPress

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdButton(
  variant: 'primary',
  child: Text('Save changes'),
)

// events: onPressed

loading state: loading

Usage

import { WyrdButton } from "@wyrd-company/react";

<WyrdButton variant="primary" isLoading>
  Save changes
</WyrdButton>

// events: onPress

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdButton(
  variant: 'primary',
  isLoading: true,
  child: Text('Save changes'),
)

// events: onPressed

danger state: default

Usage

import { WyrdButton } from "@wyrd-company/react";

<WyrdButton variant="danger">
  Delete
</WyrdButton>

// events: onPress

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdButton(
  variant: 'danger',
  child: Text('Delete'),
)

// events: onPressed

Anatomy

The specimen is the same published React component and contract example used above. Indexed markers identify only regions the contract can ground; the typed ledger keeps parts, slots, states, and semantic token bindings distinct.

ANATOMY · LIVE SPECIMEN Button primary example · contract-derived

Part root Interactive platform control root.
The rendered button boundary.
Part label Label content container.
The visible label region.
Slot label Primary visible label and accessible-name source.
Where the example supplies Save changes.
Token primary.background color.primary
The semantic primary background token applied to the root surface.

Parts

rootInteractive platform control root.
labelLabel content container.
iconIcon slot containers.
loading-indicatorNon-color-only indeterminate activity indicator shown before the stable label while loading.

Slots

labelRequired · exactly-one
leading-iconOptional · zero-or-one
trailing-iconOptional · zero-or-one

States

defaultIdle enabled state.
hoverPointer hover state on hover-capable devices.
focus-visibleKeyboard-visible focus state.
pressedActive press state.
disabledDisabled state derived from is-disabled.
loadingPending state with a visible activity indicator derived from is-loading.

Tokens

primary.backgroundcolor.primary
primary.background-hovercolor.primary-hover
primary.background-pressedcolor.primary-pressed
primary.foregroundcolor.on-primary
secondary.backgroundcolor.secondary
secondary.foregroundcolor.on-secondary
ghost.backgroundtransparent
ghost.foregroundcolor.primary
danger.backgroundcolor.error
danger.foregroundcolor.on-error
disabled.backgroundcolor.disabled
disabled.foregroundcolor.on-disabled
radiusrounded.md
padding-xspacing.lg
padding-yspacing.sm
gapspacing.sm
labeltypography.label-md
loading-indicator-sizespacing.md
loading-indicator-stroke-width2px

FIG. 1 parts: root · label · icon · loading-indicator TOL. ±0

Properties

Name	Type	Default	Summary
`variant`	`primary \| secondary \| ghost \| danger`	`primary`	Visual and semantic action emphasis.
`is-disabled`	`boolean`	`false`	Prevents activation and exposes disabled platform semantics.
`is-loading`	`boolean`	`false`	Shows pending action state while preserving dimensions and suppressing duplicate activation.

Slots & events

Slot	Cardinality	Accepts	Summary
`label`	exactly-one	`text, node`	Primary visible label and accessible-name source.
`leading-icon`	zero-or-one	`icon`	Optional icon before the label in inline flow.
`trailing-icon`	zero-or-one	`icon`	Optional icon after the label in inline flow.

Event	Payload	Summary
`press`	`source, action`	Canonical activation event emitted once per accepted activation.

Tokens

The contract's token bindings. Open the shared contextual sidebar from any example; primary swatches reflect the color you pick there. Error swatches show the active preset's values; editing any knob switches to custom and resets error to TWW · Ink.

Binding	Token
`primary.background`	`color.primary`
`primary.background-hover`	`color.primary-hover`
`primary.background-pressed`	`color.primary-pressed`
`primary.foreground`	`color.on-primary`
`secondary.background`	`color.secondary`
`secondary.foreground`	`color.on-secondary`
`ghost.background`	`transparent`
`ghost.foreground`	`color.primary`
`danger.background`	`color.error`
`danger.foreground`	`color.on-error`
`disabled.background`	`color.disabled`
`disabled.foreground`	`color.on-disabled`
`radius`	`rounded.md`
`padding-x`	`spacing.lg`
`padding-y`	`spacing.sm`
`gap`	`spacing.sm`
`label`	`typography.label-md`
`loading-indicator-size`	`spacing.md`
`loading-indicator-stroke-width`	`2px`

States

State	Source	Summary
`default`	platform	Idle enabled state.
`hover`	interaction	Pointer hover state on hover-capable devices.
`focus-visible`	platform	Keyboard-visible focus state.
`pressed`	interaction	Active press state.
`disabled`	property	Disabled state derived from is-disabled.
`loading`	property	Pending state with a visible activity indicator derived from is-loading.

SDUI

Status: serializable. Press serializes as an action reference; executable callbacks stay target-local.

Serializable	Members
Properties	`variant, is-disabled, is-loading`
Slots	`label, leading-icon, trailing-icon`
Events	`press`

  The Wyrding Way — a contract-first design system. © Wyrd Company 
   Pipeline demo
 Choose an example to inspect its pipeline context.
 Explore the shape of a brand's pipeline input: presets and knobs regenerate the illustrative excerpt below — not a compilable DESIGN.md (see the format reference). Primary swatches update live; accent, shape, density, and ground are excerpt-only; error swatches are preset-derived until any edit switches to custom (TWW · Ink errors). Component previews use the published brand package and the site's light/dark toggle.
 
  Start from
       
 * homages — shown for range, not affiliation.
 
  Tokens
 Primary updates live swatches. Accent, shape, density, and ground appear in the excerpt only. Error swatches follow the preset until you edit a knob — then they reset to TWW · Ink.
  color.primary   #26221A    color.accent   #9C7C14    rounded.md   2px    density   1.0×    ground     
 
   DESIGN.md excerpt illustrative

Examples

Anatomy

Parts

Slots

States

Tokens

Properties

Slots & events

Tokens

States

Accessibility

SDUI