Contracts

Components

Framework-neutral component contracts for core controls, regions, and states.

Specimens: 17
States: 6
Bindings: 10

Usage

Use component contracts to choose the smallest interface primitive that supports the work. These contracts describe behavior, state, and review evidence; they are not a renderer package.

Specimens

Each specimen pairs a rendered preview with required state coverage, anatomy, token roles, and source evidence from the current contract.

Component specimen

Action button

Trigger one bounded user action

Open

ready

disabled

focus visible

Anatomy

visible label
optional icon
state affordance

Tokens

text
border
focus
decision
risk

States

ready
disabled
focus-visible
loading

Anatomy

visible label
optional icon
state affordance

Evidence

Contract: action_button
Contract hash: 2494d1f5a906
Output hash: 0ba7400e5c1e

Contract

{
  "id": "action_button",
  "purpose": "Trigger one bounded user action",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible",
    "loading"
  ],
  "anatomy": [
    "visible label",
    "optional icon",
    "state affordance"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "decision",
    "risk"
  ]
}

Component specimen

Action group

Group related actions with clear priority and boundaries

Open

ready

Case action

disabled

Case action

focus visible

Case action

Anatomy

primary action
secondary actions
group label or context

Tokens

decision
risk
border
spacing

States

ready
disabled
focus-visible

Anatomy

primary action
secondary actions
group label or context

Evidence

Contract: action_group
Contract hash: fbe6ff6cffef
Output hash: d1c1e0233cac

Contract

{
  "id": "action_group",
  "purpose": "Group related actions with clear priority and boundaries",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "primary action",
    "secondary actions",
    "group label or context"
  ],
  "token_bindings": [
    "decision",
    "risk",
    "border",
    "spacing"
  ]
}

Component specimen

Form field

Collect one labeled value with help, error, and disabled affordances

Open

empty Reason Visible helper text stays with the control.

ready Reason Visible helper text stays with the control.

error Reason Add a reason before continuing. Reason is required.

disabled Reason Unavailable until evidence is complete.

focus visible Reason Visible helper text stays with the control.

Anatomy

label
control
help text
error text

Tokens

text
border
focus
status
disabled

States

empty
ready
error
disabled
focus-visible

Anatomy

label
control
help text
error text

Evidence

Contract: form_field
Contract hash: 937019114f83
Output hash: fa38389f9d33

Contract

{
  "id": "form_field",
  "purpose": "Collect one labeled value with help, error, and disabled affordances",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "label",
    "control",
    "help text",
    "error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "status",
    "disabled"
  ]
}

Component specimen

Text field

Collect short text or numeric values

Open

empty Reason Visible helper text stays with the control.

ready Reason Visible helper text stays with the control.

error Reason Add a reason before continuing. Reason is required.

disabled Reason Unavailable until evidence is complete.

focus visible Reason Visible helper text stays with the control.

Anatomy

label
input
help text
error text

Tokens

text
border
focus
status

States

empty
ready
error
disabled
focus-visible

Anatomy

label
input
help text
error text

Evidence

Contract: text_field
Contract hash: 9b9f48aedec0
Output hash: 47ce3e03d9df

Contract

{
  "id": "text_field",
  "purpose": "Collect short text or numeric values",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "label",
    "input",
    "help text",
    "error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "status"
  ]
}

Component specimen

Text area

Collect longer written input

Open

empty Handoff note Visible helper text stays with the control.

ready Handoff note Visible helper text stays with the control.

error Handoff note Add a reason before continuing. Add a handoff note.

disabled Handoff note Unavailable until evidence is complete.

focus visible Handoff note Visible helper text stays with the control.

Anatomy

label
multi-line control
help text
error text

Tokens

text
border
focus
spacing

States

empty
ready
error
disabled
focus-visible

Anatomy

label
multi-line control
help text
error text

Evidence

Contract: text_area
Contract hash: 66776c2fe1fd
Output hash: 839ec27d4f83

Contract

{
  "id": "text_area",
  "purpose": "Collect longer written input",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "label",
    "multi-line control",
    "help text",
    "error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "spacing"
  ]
}

Component specimen

Select field

Choose one value from a bounded option set

Open

empty Decision Visible helper text stays with the control.

ready Decision Visible helper text stays with the control.

error Decision Add a reason before continuing.

disabled Decision Unavailable until evidence is complete.

focus visible Decision Visible helper text stays with the control.

Anatomy

label
trigger or native select
options
help or error text

Tokens

text
border
focus
surface

States

empty
ready
error
disabled
focus-visible

Anatomy

label
trigger or native select
options
help or error text

Evidence

Contract: select_field
Contract hash: 932cd0f7bc42
Output hash: d8f4a5fcab38

Contract

{
  "id": "select_field",
  "purpose": "Choose one value from a bounded option set",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "label",
    "trigger or native select",
    "options",
    "help or error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "surface"
  ]
}

Component specimen

Checkbox group

Choose independent options from a set

Open

ready

Evidence present Receipt Manager approval Choose all evidence sources.

error

Evidence present Receipt Manager approval Select at least one evidence source.

disabled

Evidence present Receipt Manager approval Choose all evidence sources.

focus visible

Evidence present Receipt Manager approval Choose all evidence sources.

Anatomy

legend
checkbox options
help or error text

Tokens

text
border
focus
spacing

States

ready
error
disabled
focus-visible

Anatomy

legend
checkbox options
help or error text

Evidence

Contract: checkbox_group
Contract hash: bb7280a502ee
Output hash: f251d055673a

Contract

{
  "id": "checkbox_group",
  "purpose": "Choose independent options from a set",
  "required_states": [
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "legend",
    "checkbox options",
    "help or error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "spacing"
  ]
}

Component specimen

Radio group

Choose exactly one option from a set

Open

States

empty
ready
error
disabled
focus-visible

Anatomy

legend
radio options
help or error text

Evidence

Contract: radio_group
Contract hash: eb6f6b90e40a
Output hash: 6dd1227ecfb7

Contract

{
  "id": "radio_group",
  "purpose": "Choose exactly one option from a set",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "legend",
    "radio options",
    "help or error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "spacing"
  ]
}

Component specimen

Toggle

Switch a binary setting on or off

Open

ready

disabled

focus visible

Anatomy

visible label
switch control
current state text

Tokens

status
focus
disabled

States

ready
disabled
focus-visible

Anatomy

visible label
switch control
current state text

Evidence

Contract: toggle
Contract hash: b73eef734a2e
Output hash: d2390b2a9a9e

Contract

{
  "id": "toggle",
  "purpose": "Switch a binary setting on or off",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "visible label",
    "switch control",
    "current state text"
  ],
  "token_bindings": [
    "status",
    "focus",
    "disabled"
  ]
}

Component specimen

Tabs

Switch between peer sections without changing the task object

Open

ready

Receipt and approval evidence.

disabled

Receipt and approval evidence.

focus visible

Receipt and approval evidence.

Anatomy

tab list
tabs
active tab
tab panels

Tokens

surface
border
focus
text

States

ready
disabled
focus-visible

Anatomy

tab list
tabs
active tab
tab panels

Evidence

Contract: tabs
Contract hash: a2afae27cdd4
Output hash: c61bf383cbae

Contract

{
  "id": "tabs",
  "purpose": "Switch between peer sections without changing the task object",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "tab list",
    "tabs",
    "active tab",
    "tab panels"
  ],
  "token_bindings": [
    "surface",
    "border",
    "focus",
    "text"
  ]
}

Component specimen

{
  "id": "menu",
  "purpose": "Reveal a compact set of contextual commands",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "trigger",
    "menu",
    "menu items",
    "dismiss behavior"
  ],
  "token_bindings": [
    "surface",
    "border",
    "focus",
    "text"
  ]
}

Component specimen

Dialog

Interrupt the current surface for a bounded decision or focused form

Open

ready

error

focus visible

Anatomy

title
body
dismiss action
primary action

Tokens

surface
border
focus
decision
risk

States

ready
loading
error
focus-visible

Anatomy

title
body
dismiss action
primary action

Evidence

Contract: dialog
Contract hash: d0b0c5d298fa
Output hash: a386e5f5bd17

Contract

{
  "id": "dialog",
  "purpose": "Interrupt the current surface for a bounded decision or focused form",
  "required_states": [
    "ready",
    "loading",
    "error",
    "focus-visible"
  ],
  "anatomy": [
    "title",
    "body",
    "dismiss action",
    "primary action"
  ],
  "token_bindings": [
    "surface",
    "border",
    "focus",
    "decision",
    "risk"
  ]
}

Component specimen

Alert

Call attention to important status, risk, or required action

Open

ready

Case is ready for review.

focus visible

Case is ready for review.

Anatomy

status indicator
message
optional action

Tokens

status
risk
receipt
text

States

ready
focus-visible

Anatomy

status indicator
message
optional action

Evidence

Contract: alert
Contract hash: 0dd2e0e5d500
Output hash: 567c7e5c3b23

Contract

{
  "id": "alert",
  "purpose": "Call attention to important status, risk, or required action",
  "required_states": [
    "ready",
    "focus-visible"
  ],
  "anatomy": [
    "status indicator",
    "message",
    "optional action"
  ],
  "token_bindings": [
    "status",
    "risk",
    "receipt",
    "text"
  ]
}

Component specimen

Table

Compare structured rows and columns

Open

empty

Escalation queue
Case	Status
No cases	Ready
No work waiting.

ready

Escalation queue
Case	Status
RF-1842	Ready
1 case shown.

Escalation queue
Case	Status
RF-1842	Loading
1 case shown.

error

Escalation queue
Case	Status
RF-1842	Needs repair
1 case shown.

focus visible

Escalation queue
Case	Status
RF-1842	Ready
1 case shown.

Anatomy

caption or heading
headers
rows
cells
empty state

Tokens

surface
border
text
spacing

States

empty
ready
loading
error
focus-visible

Anatomy

caption or heading
headers
rows
cells
empty state

Evidence

Contract: table
Contract hash: 5c352b7dd17f
Output hash: 6d550ee2f77c

Contract

{
  "id": "table",
  "purpose": "Compare structured rows and columns",
  "required_states": [
    "empty",
    "ready",
    "loading",
    "error",
    "focus-visible"
  ],
  "anatomy": [
    "caption or heading",
    "headers",
    "rows",
    "cells",
    "empty state"
  ],
  "token_bindings": [
    "surface",
    "border",
    "text",
    "spacing"
  ]
}

Component specimen

Panel

Group related work, evidence, or controls in a bounded region

Open

ready

Evidence

Receipt, policy, and customer note are grouped here.

Evidence

Loading evidence.

error

Evidence

Evidence conflict needs review.

Anatomy

heading
content region
optional actions

Tokens

surface
border
spacing
text

States

ready
loading
error

Anatomy

heading
content region
optional actions

Evidence

Contract: panel
Contract hash: 459196b00570
Output hash: 54dc298a6351

Contract

{
  "id": "panel",
  "purpose": "Group related work, evidence, or controls in a bounded region",
  "required_states": [
    "ready",
    "loading",
    "error"
  ],
  "anatomy": [
    "heading",
    "content region",
    "optional actions"
  ],
  "token_bindings": [
    "surface",
    "border",
    "spacing",
    "text"
  ]
}

Component specimen

Card

Summarize one repeated item or choice

Open

ready

Refund RF-1842

Policy exception with receipt evidence.

Updated 4 min ago

disabled

Refund RF-1842

Policy exception with receipt evidence.

Updated 4 min ago

focus visible

Refund RF-1842

Policy exception with receipt evidence.

Updated 4 min ago

Anatomy

item title
summary
metadata
optional action

Tokens

surface
border
spacing
text

States

ready
disabled
focus-visible

Anatomy

item title
summary
metadata
optional action

Evidence

Contract: card
Contract hash: 40eaf0733f40
Output hash: 76f5180a2273

Contract

{
  "id": "card",
  "purpose": "Summarize one repeated item or choice",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "item title",
    "summary",
    "metadata",
    "optional action"
  ],
  "token_bindings": [
    "surface",
    "border",
    "spacing",
    "text"
  ]
}

Component specimen

Status message

Report progress, result, validation, or completion

Open

ready

Ready Decision can be handed off.

Saving Decision can be handed off.

error

Needs repair Add missing evidence before handoff.

Anatomy

status text
severity or result
optional next action

Tokens

status
risk
receipt
text

States

ready
loading
error

Anatomy

status text
severity or result
optional next action

Evidence

Contract: status_message
Contract hash: d56c305dd570
Output hash: f04d9f8adfa5

Contract

{
  "id": "status_message",
  "purpose": "Report progress, result, validation, or completion",
  "required_states": [
    "ready",
    "loading",
    "error"
  ],
  "anatomy": [
    "status text",
    "severity or result",
    "optional next action"
  ],
  "token_bindings": [
    "status",
    "risk",
    "receipt",
    "text"
  ]
}

Component contracts

Core UI component contracts
Component	Purpose	States	Review
`action_button` Action button	Trigger one bounded user action	ready, disabled, focus-visible, loading	action comes from the workflow; risky actions have approval-boundary evidence
`action_group` Action group	Group related actions with clear priority and boundaries	ready, disabled, focus-visible	primary action is singular; secondary actions remain adjacent to their object
`form_field` Form field	Collect one labeled value with help, error, and disabled affordances	empty, ready, error, disabled, focus-visible	label uses domain vocabulary; disabled reason is readable
`text_field` Text field	Collect short text or numeric values	empty, ready, error, disabled, focus-visible	input type matches the value; validation is visible and textual
`text_area` Text area	Collect longer written input	empty, ready, error, disabled, focus-visible	expected content is clear; long content does not collapse nearby controls
`select_field` Select field	Choose one value from a bounded option set	empty, ready, error, disabled, focus-visible	empty option is clear when optional; selected value is visible
`checkbox_group` Checkbox group	Choose independent options from a set	ready, error, disabled, focus-visible	long labels wrap cleanly; options remain independent
`radio_group` Radio group	Choose exactly one option from a set	empty, ready, error, disabled, focus-visible	option labels are comparable; default selection is intentional
`toggle` Toggle	Switch a binary setting on or off	ready, disabled, focus-visible	label names the setting; state change is reversible or bounded
`tabs` Tabs	Switch between peer sections without changing the task object	ready, disabled, focus-visible	tabs are peers; active state is visible
`menu` Menu	Reveal a compact set of contextual commands	ready, disabled, focus-visible	commands are contextual; primary path remains visible
`dialog` Dialog	Interrupt the current surface for a bounded decision or focused form	ready, loading, error, focus-visible	primary action is visually final; cancel or dismiss precedes primary action
`alert` Alert	Call attention to important status, risk, or required action	ready, focus-visible	severity matches the action needed; message explains next step
`table` Table	Compare structured rows and columns	empty, ready, loading, error, focus-visible	columns support decisions; empty and loading states are clear
`panel` Panel	Group related work, evidence, or controls in a bounded region	ready, loading, error	panel groups one coherent concern; actions are adjacent to content
`card` Card	Summarize one repeated item or choice	ready, disabled, focus-visible	card represents one object; interactive area is clear
`status_message` Status message	Report progress, result, validation, or completion	ready, loading, error	message names the user-relevant result; completion leaves a receipt

Review checks

Use only known component contract ids when citing component evidence.
Provide required state coverage for every component contract used.
Keep risky action evidence separate from component evidence.
Do not use renderer or component-library compliance as proof of activity fit.

Accessibility

Controls need accessible names, keyboard operation, visible focus, and target-size evidence.
Forms need labels, instructions, text errors, and status messages.
Dialogs, menus, tabs, and custom widgets need name-role-value and focus-management evidence.

Examples

Action with a boundary

Use
Use an action button when the user can trigger one clear outcome with visible state.

Watch for
Do not expose risky or destructive action without approval-boundary evidence.
Field with clear state

Use
Use field contracts when labels, help, validation, disabled state, and focus must stay together.

Watch for
Do not rely on placeholder text or color-only errors.

Components

Usage

Specimens

Action button

Action group

Form field

Text field

Text area

Select field

Checkbox group

Radio group

Toggle

Tabs

Menu

Dialog

Confirm approval

Confirm approval

Confirm approval

Confirm approval

Alert

Table

Panel

Evidence

Evidence

Evidence

Card

Refund RF-1842

Refund RF-1842

Refund RF-1842

Status message

Component contracts

Review checks

Accessibility

Examples

Action with a boundary

Field with clear state