button-example

Worked Button contract example

Type: Example
Status: Active illustration
Canonical for: A compact worked mapping across the candidate Design and Development Contracts
Depends on: Candidate package; this is not an evidence-derived requirement or validated optimum

This example does not propose PDS property names, Button variants or a production serialization.

Shared kernel excerpt

Field	Illustrative value
conceptId	ds.component.action-button
conceptType	Component
preferredLabel	Button
description	Invokes an immediate action in the current product context.
status	Stable
productScope	Shared system

Linked alternatives:

• ds.component.link for navigation;
• ds.component.toggle-control for persistent binary state;
• a product pattern contract for multi-step confirmation.

Design Contract excerpt

Selection boundary

Use when: the user intentionally invokes an immediate action such as saving, creating, retrying or opening a dialog.

Avoid when: the interaction primarily navigates to another resource, changes a persistent binary setting, or selects an option from a set.

Semantic dimensions

Dimension	Concepts	Meaning
Action-group emphasis	emphasis.high, .medium, .low	Relative prominence within a named action group.
Impact	impact.neutral, .destructive	Consequence of activation; independent from emphasis.
State	state.enabled, .disabled, .loading	Current interaction condition; independent from purpose.

Illustrative rules:

• button.action-group.single-high: at most one emphasis.high Button in the same action group.
• button.impact.independent: destructive impact does not by itself determine emphasis.
• button.navigation.avoid: use the Link concept when the primary outcome is navigation.
• button.icon.accessible-name: an icon-only Button requires an accessible name.

The contract does not require these semantic dimensions to become public runtime props. It requires their mapping to the actual design and code APIs to be explicit.

Mapping across layers

Semantic concept	Illustrative Figma value	Illustrative code value	Mapping
emphasis.high	Hierarchy=Primary	appearance="primary"	Exact within an action-group scope
emphasis.medium	Hierarchy=Secondary	appearance="secondary"	Exact within an action-group scope
emphasis.low	Hierarchy=Tertiary	appearance="subtle"	Contextual visual realization
impact.destructive	Tone=Critical	tone="danger"	Exact consequence mapping
state.loading	Loading=True	loading={true}	Exact state mapping

The labels differ, but the mapping makes the governed concept addressable. If the actual system mixes these concepts in one property, the mapping should record that rather than pretending the API is factorized.

Development Contract excerpt

Illustrative implementation binding:

Field	Value
Framework	React
Package	@example/design-system
Export/import	Button
Storybook	components-button
Figma mapping	Component key and Code Connect source

Illustrative public API mapping:

API property	Type	Semantic dimension	Notes
appearance	finite string union	Action-group emphasis / visual realization	Every value maps to an emphasis concept and treatment.
tone	finite string union	Impact	Does not imply emphasis.
loading	boolean	State	Suppresses duplicate activation according to implementation behavior.
disabled	boolean	State	Must preserve disabled semantics and focus policy documented by the system.
type	button/submit/reset union	Native behavior	Form context determines outcome.
onClick	event callback	Action event	Payload and timing are implementation-defined and documented.

What an agent should receive for a decision

For “Add a destructive final confirmation beside Cancel,” the projected packet might include:

• Button purpose and Link/Toggle exclusions;
• the current action-group scope;
• impact and emphasis as separate concepts;
• the final-confirmation pattern rule;
• the closest valid alternatives;
• actual Figma/code mappings for the supported implementation;
• icon-label and focus requirements;
• applicable validators.

It should not automatically receive every Button story, every token value or unrelated product pattern.

What remains outside this component contract

• whether deletion is permitted;
• whether confirmation is legally required;
• user authorization;
• rollback implementation;
• product-specific copy approval;
• the business rule determining which entity is affected.

The component contract can represent these conditions and states, but the product or platform owns their truth.