Primitive contract

CopyButton

Defines activation, success, reset, failure, disabled, and announcement obligations while leaving clipboard access in gallery or consumer code.

Explicit copy command with visible feedback · @sanchika/primitives

Purpose and semantics

Defines activation, success, reset, failure, disabled, and announcement obligations while leaving clipboard access in gallery or consumer code.

Recommended semantic: Use a native button with an accessible name that explains the target and a separate polite status region.

Anatomy

button

Explicit activation command.

label

Visible default/copied/failed state.

status

Polite success or failure announcement.

Finite variants and important states

Variant · state: idle, copied, failed
Variant · size: sm, md
Required states: idle, copied, failed, disabled
Class hooks: .sk-copy-button · .sk-copy-button__label · .sk-copy-button__status

Composed synthetic exemplar

Rendered state matrix

CopyButton: 4 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.

idleThe idle contract remains visible and inspectable.

copiedVisible confirmation reinforces the announced result.

failedThe original value remains available for manual recovery.

disabledUnavailable with its reason preserved in nearby text.

Accessibility and consumer responsibility

Keyboard and screen reader

Native button activation
Focus remains on button
No clipboard access without activation
Accessible name identifies target
Polite status announces success/failure
Reset does not generate unnecessary chatter

Consumer owns

Call Clipboard API on activation
Handle denial
Reset label
Keep focus
Avoid sensitive copy

Mobile

Label wraps and practical target remains reachable

Reduced motion and forced colors

Copied wording remains immediately visible and announced without movement.

Button boundary and visible state remain

Compact API reference

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