Contracts

Patterns

Surface patterns that connect activity purpose to required regions, controls, and completion behavior.

Specimens: 8
Regions: 31
Controls: 23

Usage

Use surface patterns after the activity and surface type are clear. A pattern names the regions, controls, completion behavior, and disclosure boundary the interface must support.

Specimens

Each specimen pairs a rendered miniature surface with required regions, expected controls, completion behavior, and source evidence from the current contract.

Pattern specimen

Marketing surface

Orient a visitor to an offer and move them to a clear next step

Open

marketing Marketing surface

offer

The main promise is stated before supporting proof.

proof

Marketing surface region 2 supports orient a visitor to an offer and move them to a clear next step

primary next step

Marketing surface region 3 supports orient a visitor to an offer and move them to a clear next step

visitor understands the offer and can take the next step

Regions

offer
proof
primary next step

Controls

primary call to action
secondary information path

Evidence

Surface: marketing
Contract hash: 4173a9cd2dce
Output hash: aeaed6af4ee7

Contract

{
  "id": "marketing",
  "surface_type": "marketing",
  "purpose": "Orient a visitor to an offer and move them to a clear next step",
  "required_regions": [
    "offer",
    "proof",
    "primary next step"
  ],
  "expected_controls": [
    "primary call to action",
    "secondary information path"
  ],
  "completion_or_handoff": "visitor understands the offer and can take the next step"
}

Pattern specimen

Workbench

Help a user repeatedly inspect, compare, decide, and act

Open

workbench Workbench

work queue

Workbench region 1 supports help a user repeatedly inspect, compare, decide, and act

detail workspace

Workbench region 2 supports help a user repeatedly inspect, compare, decide, and act

evidence

Visible support for the decision stays adjacent to the work.

decision or handoff

The next action is bounded by the review context.

selected work item advances or leaves a clear handoff

Regions

work queue
detail workspace
evidence
decision or handoff

Controls

selection
filter or sort
decision action
handoff action

Evidence

Surface: workbench
Contract hash: 257f71ef299d
Output hash: 4da1ece7d40a

Contract

{
  "id": "workbench",
  "surface_type": "workbench",
  "purpose": "Help a user repeatedly inspect, compare, decide, and act",
  "required_regions": [
    "work queue",
    "detail workspace",
    "evidence",
    "decision or handoff"
  ],
  "expected_controls": [
    "selection",
    "filter or sort",
    "decision action",
    "handoff action"
  ],
  "completion_or_handoff": "selected work item advances or leaves a clear handoff"
}

Pattern specimen

Operator review

Review produced work, evidence, risk, and a bounded next action

Open

operator review Operator review

produced work

Operator review region 1 supports review produced work, evidence, risk, and a bounded next action

evidence

Visible support for the decision stays adjacent to the work.

risk

Risk is named in domain terms before action.

decision

The next action is bounded by the review context.

receipt

Operator review region 5 supports review produced work, evidence, risk, and a bounded next action

review produces a decision reason and receipt

Regions

produced work
evidence
risk
decision
receipt

Controls

approve or accept
return or request changes
handoff action

Evidence

Surface: operator_review
Contract hash: bc9659d55d29
Output hash: 2efe4cbd5538

Contract

{
  "id": "operator_review",
  "surface_type": "operator_review",
  "purpose": "Review produced work, evidence, risk, and a bounded next action",
  "required_regions": [
    "produced work",
    "evidence",
    "risk",
    "decision",
    "receipt"
  ],
  "expected_controls": [
    "approve or accept",
    "return or request changes",
    "handoff action"
  ],
  "completion_or_handoff": "review produces a decision reason and receipt"
}

Pattern specimen

Form flow

Collect or change structured information with validation

Open

form flow Form flow

inputs

Form flow region 1 supports collect or change structured information with validation

validation

Form flow region 2 supports collect or change structured information with validation

review or submit

Form flow region 3 supports collect or change structured information with validation

confirmation

Form flow region 4 supports collect or change structured information with validation

valid information is saved or submitted with confirmation

Regions

inputs
validation
review or submit
confirmation

Controls

field controls
submit action
cancel or back action

Evidence

Surface: form_flow
Contract hash: 4c67a2c72b88
Output hash: 4785a5ae4525

Contract

{
  "id": "form_flow",
  "surface_type": "form_flow",
  "purpose": "Collect or change structured information with validation",
  "required_regions": [
    "inputs",
    "validation",
    "review or submit",
    "confirmation"
  ],
  "expected_controls": [
    "field controls",
    "submit action",
    "cancel or back action"
  ],
  "completion_or_handoff": "valid information is saved or submitted with confirmation"
}

Pattern specimen

Dashboard monitor

Track status, exceptions, trends, or operational health

Open

dashboard monitor Dashboard monitor

status summary

Current state is summarized without hiding exceptions.

exceptions

Dashboard monitor region 2 supports track status, exceptions, trends, or operational health

trend or comparison

Dashboard monitor region 3 supports track status, exceptions, trends, or operational health

follow-up path

Dashboard monitor region 4 supports track status, exceptions, trends, or operational health

user knows current state and whether follow-up is needed

Regions

status summary
exceptions
trend or comparison
follow-up path

Controls

filter
time range
drill in

Evidence

Surface: dashboard_monitor
Contract hash: 85239d6bde9e
Output hash: 18f0dc9cd570

Contract

{
  "id": "dashboard_monitor",
  "surface_type": "dashboard_monitor",
  "purpose": "Track status, exceptions, trends, or operational health",
  "required_regions": [
    "status summary",
    "exceptions",
    "trend or comparison",
    "follow-up path"
  ],
  "expected_controls": [
    "filter",
    "time range",
    "drill in"
  ],
  "completion_or_handoff": "user knows current state and whether follow-up is needed"
}

Pattern specimen

Content or report

Help the user read, understand, cite, or share information

Open

content report Content or report

summary

Content or report region 1 supports help the user read, understand, cite, or share information

sections

Content or report region 2 supports help the user read, understand, cite, or share information

evidence or references

Visible support for the decision stays adjacent to the work.

share or export

Content or report region 4 supports help the user read, understand, cite, or share information

reader understands, cites, exports, or shares the material

Regions

summary
sections
evidence or references
share or export

Controls

table of contents
copy or export
reference navigation

Evidence

Surface: content_report
Contract hash: c2df708d839a
Output hash: a325f386cf7f

Contract

{
  "id": "content_report",
  "surface_type": "content_report",
  "purpose": "Help the user read, understand, cite, or share information",
  "required_regions": [
    "summary",
    "sections",
    "evidence or references",
    "share or export"
  ],
  "expected_controls": [
    "table of contents",
    "copy or export",
    "reference navigation"
  ],
  "completion_or_handoff": "reader understands, cites, exports, or shares the material"
}

Pattern specimen

Setup or debugging tool

Configure, inspect, test, or troubleshoot machinery

Open

setup debug tool Setup or debugging tool

configuration

Settings are visible because setup is the activity.

test result

Setup or debugging tool region 2 supports configure, inspect, test, or troubleshoot machinery

diagnostic detail

Setup or debugging tool region 3 supports configure, inspect, test, or troubleshoot machinery

next fix

Setup or debugging tool region 4 supports configure, inspect, test, or troubleshoot machinery

setup is valid or failure has a cause and next fix

Regions

configuration
test result
diagnostic detail
next fix

Controls

run test
copy diagnostic
retry or repair

Evidence

Surface: setup_debug_tool
Contract hash: cdd443f0eb47
Output hash: d636a3cf026f

Contract

{
  "id": "setup_debug_tool",
  "surface_type": "setup_debug_tool",
  "purpose": "Configure, inspect, test, or troubleshoot machinery",
  "required_regions": [
    "configuration",
    "test result",
    "diagnostic detail",
    "next fix"
  ],
  "expected_controls": [
    "run test",
    "copy diagnostic",
    "retry or repair"
  ],
  "completion_or_handoff": "setup is valid or failure has a cause and next fix"
}

Pattern specimen

Conversation

Support open-ended exchange where the thread is the product surface

Open

conversation Conversation

message history

Conversation region 1 supports support open-ended exchange where the thread is the product surface

composer

Message creation stays close to context and status.

context or attachments

Conversation region 3 supports support open-ended exchange where the thread is the product surface

status

Current state is summarized without hiding exceptions.

conversation continues, recovers, or closes with context intact

Regions

message history
composer
context or attachments
status

Controls

send
attach or reference
recover or retry

Evidence

Surface: conversation
Contract hash: 02f03c588f7c
Output hash: 8c8d8f296005

Contract

{
  "id": "conversation",
  "surface_type": "conversation",
  "purpose": "Support open-ended exchange where the thread is the product surface",
  "required_regions": [
    "message history",
    "composer",
    "context or attachments",
    "status"
  ],
  "expected_controls": [
    "send",
    "attach or reference",
    "recover or retry"
  ],
  "completion_or_handoff": "conversation continues, recovers, or closes with context intact"
}

Surface patterns

Surface pattern contracts
Pattern	Purpose	Regions	Controls
`marketing` Marketing surface	Orient a visitor to an offer and move them to a clear next step	offer, proof, primary next step	primary call to action, secondary information path
`workbench` Workbench	Help a user repeatedly inspect, compare, decide, and act	work queue, detail workspace, evidence, decision or handoff	selection, filter or sort, decision action, handoff action
`operator_review` Operator review	Review produced work, evidence, risk, and a bounded next action	produced work, evidence, risk, decision, receipt	approve or accept, return or request changes, handoff action
`form_flow` Form flow	Collect or change structured information with validation	inputs, validation, review or submit, confirmation	field controls, submit action, cancel or back action
`dashboard_monitor` Dashboard monitor	Track status, exceptions, trends, or operational health	status summary, exceptions, trend or comparison, follow-up path	filter, time range, drill in
`content_report` Content or report	Help the user read, understand, cite, or share information	summary, sections, evidence or references, share or export	table of contents, copy or export, reference navigation
`setup_debug_tool` Setup or debugging tool	Configure, inspect, test, or troubleshoot machinery	configuration, test result, diagnostic detail, next fix	run test, copy diagnostic, retry or repair
`conversation` Conversation	Support open-ended exchange where the thread is the product surface	message history, composer, context or attachments, status	send, attach or reference, recover or retry

Review checks

The selected pattern must match the chosen surface type.
Required regions and expected controls need evidence in the generated interface.
Completion or handoff behavior must leave a result, reason, or next action.
Disclosure boundaries still control whether diagnostic detail belongs on the surface.

Accessibility

Patterns with charts, media, or visual status need text alternatives and non-color cues.
Multi-region layouts need keyboard order that preserves the work sequence.
Dense workbenches and dashboards need responsive no-overflow evidence.

Examples

Workbench activity

Use
Use the workbench pattern when the user repeatedly inspects, compares, decides, and hands off work items.

Watch for
Do not turn repeated review work into a numbered wizard without staged-flow evidence.
Setup or debugging

Use
Use the setup pattern when implementation details are the work material.

Watch for
Do not leak diagnostics into product surfaces where the activity is not setup, auditing, or debugging.

Usage

Specimens

Surface patterns

Review checks

Accessibility

Examples

Workbench activity

Setup or debugging