Contracts

Patterns

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

Surface patterns

Choose after the activity and surface type are clear: use what the participant is trying to accomplish and what completion needs to mean. Every public pattern links to one fictional consumer-domain screen below; the examples show required regions and controls through distinct UI compositions.

Surface pattern contracts
Pattern	Use when	Done means	Example
`marketing` Marketing surface	Orient a visitor to an offer and move them to a clear next step	visitor understands the offer and can take the next step	View Marketing surface example
`workbench` Workbench	Help a user repeatedly inspect, compare, decide, and act	selected work item advances or leaves a clear handoff	View Workbench example
`operator_review` Operator review	Review produced work, evidence, risk, and a bounded next action	review produces a decision reason and receipt	View Operator review example
`form_flow` Form flow	Collect or change structured information with validation	valid information is saved or submitted with confirmation	View Form flow example
`dashboard_monitor` Dashboard monitor	Track status, exceptions, trends, or operational health	user knows current state and whether follow-up is needed	View Dashboard monitor example
`content_report` Content or report	Help the user read, understand, cite, or share information	reader understands, cites, exports, or shares the material	View Content or report example
`setup_debug_tool` Setup or debugging tool	Configure, inspect, test, or troubleshoot machinery	setup is valid or failure has a cause and next fix	View Setup or debugging tool example
`conversation` Conversation	Support open-ended exchange where the thread is the product surface	conversation continues, recovers, or closes with context intact	View Conversation example

Examples: 8; One for every public pattern.
Regions: 31; Required regions across patterns.
Controls: 23; Expected control families across patterns.

Pattern examples

Each fictional composition renders a recognizable surface UI with consumer-domain content, contextual controls, and a visible completion or handoff. The scenarios are illustrative rather than customer evidence; contract and source evidence stays available in the collapsed details.

Fictional screen example · Weeknight meal planning

Marketing surface

Understand the offer, inspect a sample plan and trust signals, and choose whether to try it.

Fictional static UI example

Savor How it works Recipes Pricing

Five dinners. One calm week.

Get five flexible dinners planned around the food your household already enjoys.

Flexible recipes, one organized grocery list, and simple swaps for nights when plans change.

See a sample plan

4.8/5: member rating
$34: average weekly savings

No card required · Cancel any time

Pattern details

Regions

offer
proof
primary next step

Controls

primary call to action
secondary information path

Evidence

Surface: marketing
Contract hash: 4173a9cd2dce
Output hash: 0032d8359971

Contract excerpt

{
  "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"
}

Fictional screen example · Apartment shortlist

Workbench

Move through saved homes, compare practical evidence, and decide which listing to advance or share.

Fictional static UI example

Home	Total
Selected apartment:	$2,585
32 Garden Lane	$2,640
8 Lakeview Court	$2,710
77 Mercer Avenue	$2,760

Top match

184 Oak Street

$2,420/mo

Budget fit$165 under max

Commute rank2nd of 4

Move-inSeptember 15

Commute: 24 min
Monthly total: $2,585
Laundry: In unit

What stands out

Quiet street after 8 PM
Groceries within a 6-minute walk
$45 pet fee included in total

Pattern details

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: 825514945965

Contract excerpt

{
  "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"
}

Fictional screen example · Family trip review

Operator review

Review the proposed days, reservation evidence, and practical risks before approving or revising the trip.

Fictional static UI example

Saturday · Museum CampusAquarium, lakefront, and an easy dinner

9:00
Shedd AquariumTimed entry · confirmation held
1:15
Lakefront lunchIndoor backup nearby
3:00
Architecture cruise35-minute transfer with stroller
6:30
Pizza near the hotelReservation optional

Changes requestedChanges requested for Saturday; Version 3 records the concern and the family reviewer.

Pattern details

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: 9635daffb29b

Contract excerpt

{
  "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"
}

Fictional screen example · Grocery delivery checkout

Form flow

Enter delivery details, resolve validation, review the basket, and place the order.

Fictional static UI example

FreshCart · 18 items

Delivery checkout

Completed step: Basket
Completed step: Delivery
Completed step: Review
Confirmation

Delivery details

Address

Delivery window

Phone for substitutions

Substitutions

Validation complete. The phone number is verified for live substitution approval.

Items: $82.40
Delivery: $4.99
Estimated total: $87.39

Pattern details

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: e6eb8555c18e

Contract excerpt

{
  "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"
}

Fictional screen example · Home energy monitor

Dashboard monitor

Understand current energy use, find unusual devices, compare the weekly trend, and decide whether to investigate.

Fictional static UI example

Today18.4 kWh7% below usual

Current draw1.2 kWMostly heating

Estimated month$142$11 under plan

Daily use

Down after the thermostat change

−9%

Wed	Thu	Fri	Sat	Sun	Mon	Tue
23.1	21.4	22.2	20.1	19.4	18.9	18.4

kWh per day · Tuesday is 9% below last Wednesday

Needs attention

Device	Change
Water heater	+18%
Dehumidifier	+9%

Pattern details

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: 684808409254

Contract excerpt

{
  "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"
}

Fictional screen example · Household budget report

Content or report

Read the monthly summary, inspect category details and source transactions, and share the report.

Fictional static UI example

$190 below plan

August stayed on track

Total spending was $4,280. Grocery costs rose, while transport and flexible spending came in lower than planned.

Category	Actual	Plan	Result
Housing	$2,120	$2,120	On plan
Food	$760	$650	$110 over
Transport	$410	$520	$110 under
Everything else	$990	$1,180	$190 under

Why food was higher

Two hosted dinners added $96. Every category total is backed by its source transactions.

View transactions

Pattern details

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: c6d5b5069f4b

Contract excerpt

{
  "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"
}

Fictional screen example · Home Wi-Fi connection test

Setup or debugging tool

Choose the network and room, run a test, inspect the result, and follow a specific repair step.

Fictional static UI example

Connected, but the signal is weak

Browsing should work; video calls may become unstable.

Room diagnostic

download   38 Mbps
latency    42 ms
signal    -72 dBm
channel     149
mesh hop      2

Pattern details

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: be43d93cadd3

Contract excerpt

{
  "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"
}

Fictional screen example · Pet-care handoff

Conversation

Continue a care exchange with the feeding plan, medication note, attachments, and delivery status intact.

Fictional static UI example

Luna · Weekend care

Latest update delivered · medication question waiting

Delivered

Sam · 8:12 AM
Luna ate all of breakfast and had her morning walk.
You · 8:18 AM
Perfect—thank you. Her blue tablet is due with dinner.
Delivered
Sam · 5:42 PM
Should I hide the tablet in food, or give it just after she eats?
Earlier update · recovered
The photo upload finished after reconnecting.

Pattern details

Regions

message history
composer
context or attachments
status

Controls

send
attach or reference
recover or retry

Evidence

Surface: conversation
Contract hash: 02f03c588f7c
Output hash: 5a149c0f8f1c

Contract excerpt

{
  "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"
}

Presentation profiles

Presentation profiles specialize a surface pattern after the activity, interaction contract, and active design-system source are established. Their status identifies whether the profile is supported or still proposed; they do not reclassify the activity or select a runtime renderer.

Surface presentation profiles
Profile	Status	Surface	Presentation	Compact behavior
`judgmentkit.workbench.operational-v1` JudgmentKit Workbench Operational	supported	workbench `workbench`	operational; flat_border_led; system appearance	Provide an explicit, reversible path between list, detail, decision, and completion without horizontal overflow.
`judgmentkit.artifact-inspector.v1` JudgmentKit Artifact Inspector	proposed	artifact_inspector `artifact-inspector`	artifact-first contextual; artifact_dominant; system appearance	Keep the artifact primary, move support into a temporary edge affordance or contextual tray, and preserve the active locus, feedback, recovery, zoom, reflow, and non-drag alternatives together without obstruction.

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.