Primitive contract

Button

Triggers an action without implying navigation and preserves the v0.0.2 tone, size, class, and visible-state contract.

Command trigger · @sanchika/primitives

Purpose and semantics

Triggers an action without implying navigation and preserves the v0.0.2 tone, size, class, and visible-state contract.

Recommended semantic: Prefer native button with an explicit type. Non-button role=button implementations remain a consumer exception with full APG obligations.

Anatomy

label

Stable accessible command name.

optional icon

Supporting icon that does not replace the label.

loading indicator

Visual pending indicator that does not change intrinsic button size.

Finite variants and important states

Variant · tone: brand, neutral, danger
Variant · size: sm, md, lg
Required states: default, hover, focus-visible, pressed, disabled, loading
Class hooks: .sk-button · .sk-tone-brand · .sk-tone-neutral · .sk-tone-danger · .sk-size-sm · .sk-size-md · .sk-size-lg

Composed synthetic exemplar

Rendered state matrix

Button: 6 required states

Each specimen starts from the package-owned example and contract state inventory. Simulated pointer and focus frames are labelled; consumers still verify real interaction in context.

defaultSettled and available for its documented job.

hoverPointer acknowledgement; the label and action stay unchanged.

focus visibleKeyboard focus remains explicit and independent of motion.

pressedActivation is acknowledged without implying success.

disabledUnavailable with its reason preserved in nearby text.

loadingThe owner exposes busy state while geometry stays stable.

Accessibility and consumer responsibility

Keyboard and screen reader

Native button activation
Space and Enter for role=button exceptions
Suppress all activation paths when aria-disabled
Keep focus predictable after activation
Provide an accessible name
Expose aria-pressed for toggles
Expose aria-busy for loading
Associate disabled reason when needed

Consumer owns

Implement runtime action and loading logic
Manage focus after workflows
Suppress activation for aria-disabled
Provide visible disabled reasons

Mobile

Labels wrap
The control stays within available width
Primary mobile actions should use the large size or consumer-owned full-width composition

Reduced motion and forced colors

Transitions are removed while the static loading indicator and visible pending text/state remain.

Focus uses system Highlight
Control boundary uses ButtonText
Disabled and pressed state remain visible without authored color

Compact API reference

Package: @sanchika/primitives
CSS: @sanchika/primitives/styles.css
Contract: primitiveSpecs.find((contract) => contract.name === "Button")
Primary class: .sk-button