action — wyrd.component.icon-button

IconButton

Square icon-only action primitive named by an explicit accessible label.

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

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

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: IconButton  tag: wyrd-icon-button  package: wyrd.component.icon-button  title: IconButton  summary: Square icon-only action primitive named by an explicit accessible label.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: action  composition: single-slot  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: label      type:        kind: string      required: true      serializable: true      summary: Accessible name for the icon-only button.    - 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: icon      required: true      cardinality: exactly-one      accepts:        - component        - icon      summary: Visible icon content.  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 derived from is-loading.  parts:    - name: root      summary: Interactive platform control root.      slots:        - icon    - name: icon      summary: Icon slot container.      slots:        - icon  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    size: spacing.xl    padding: spacing.sm    icon-size: spacing.mdmessages: []obligations:  accessibility:    role: button    name: Label property provides the accessible name.    keyboard:      - Enter activates the button.      - Space activates the button.    semantics:      - Web projections set aria-label from the label property because visible content is icon-only.      - Flutter projections expose Semantics label and button state from the label property.      - Disabled state is exposed through native disabled semantics where the target has them.      - Loading state keeps the accessible name stable and prevents duplicate activation without dimming below contrast.  behavior:    model: stateless    interactions:      - Activation emits press when the button is enabled and not loading.      - Touch activation does not create hover state.    hostEffects:      - Dispatch activation event.      - Invoke action binding for SDUI when present.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact  sdui:    status: serializable    serializableProperties:      - label      - variant      - is-disabled      - is-loading    serializableSlots:      - icon    eventBindings:      - press    notes: IconButton serializes its label, visual state, icon slot, and optional press binding.examples:  - name: primary    state: default    properties:      label: Save      variant: primary    slots:      icon: save  - name: loading    state: loading    properties:      label: Saving      variant: primary      is-loading: true    slots:      icon: save  - name: danger    state: default    properties:      label: Delete      variant: danger    slots:      icon: 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 { WyrdIconButton } from "@wyrd-company/react";

<WyrdIconButton label="Save" variant="primary" icon="save" />

// events: onPress

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdIconButton(
  label: 'Save',
  variant: 'primary',
  icon: Text('save'),
)

// events: onPressed

loading state: loading

Usage

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

<WyrdIconButton label="Saving" variant="primary" isLoading icon="save" />

// events: onPress

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdIconButton(
  label: 'Saving',
  variant: 'primary',
  isLoading: true,
  icon: Text('save'),
)

// events: onPressed

danger state: default

Usage

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

<WyrdIconButton label="Delete" variant="danger" icon="delete" />

// events: onPress

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdIconButton(
  label: 'Delete',
  variant: 'danger',
  icon: Text('delete'),
)

// events: onPressed

Properties

Name	Type	Default	Summary
`label`	`string`	`undefined`	Accessible name for the icon-only button.
`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
`icon`	exactly-one	`component, icon`	Visible icon content.

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`
`size`	`spacing.xl`
`padding`	`spacing.sm`
`icon-size`	`spacing.md`

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 derived from is-loading.

SDUI

Status: serializable. IconButton serializes its label, visual state, icon slot, and optional press binding.

Serializable	Members
Properties	`label, variant, is-disabled, is-loading`
Slots	`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

Properties

Slots & events

Tokens

States

Accessibility

SDUI