Design system

Components

Reusable JudgmentKit components and states, informed by the breadth of Simple Design System without copying its styling.

Inventory

Simple Design System sets the breadth benchmark. All 128 families and 354 variants are accounted for; JudgmentKit's current library contains 17 reusable components and 65 state examples.

Reference families
128
122 public and 6 hidden
Reference variants
354
336 public and 18 hidden
JudgmentKit components
17
Every component is shown below
State examples
65
Meaningful states shown where relevant

Standalone icons are excluded from this count because JudgmentKit maintains its icon library separately.

How the reference maps to JudgmentKit

Inventory parity

128/128 families

354/354 variants accounted for.

Public
122 public families / 336 public variants
Hidden
6 hidden families / 18 hidden variants

Standalone icons are excluded; icon-bearing component families remain in the accounting.

Semantic normalization

128/128 families classified

304/354 reference variants are axis-bearing and semantically normalized; the remaining 50 are singleton masters with no variant axes.

Axis-bearing
78 families / 304 variants
Singleton masters
50 families / 50 masters
Semantic axes
105/105 classified
Audit metadata
1 partial / 49 without axis metadata

Family disposition and variant-axis semantics are recorded separately.

  • component: 31 families
  • variant: 4 families
  • internal part: 22 families
  • pattern: 33 families
  • template: 22 families
  • typography role: 13 families
  • authoring helper: 3 families

Runtime candidate

17/17 contract IDs have local implementation candidates

0/65 required states currently verified

Scenario representation
65/65 required-state scenarios represented
Pending implementation candidates
0
Unverified required states
65
Current evidence
0 verified / 65 scenario records
Exact Figma variant evidence
0/354 verified

Usage

Choose the component that matches the user's task, then inspect every state the interface needs to handle. The examples below use the same JudgmentKit components intended for product interfaces, not look-alike specimen controls.

Components

Explore each component in the states it needs to handle. Interact with the controls directly; supporting details stay collapsed until requested.

Action button

Trigger one bounded user action

readyunverified
Activations: 0
disabledunverified

Unavailable until receipt evidence is complete.

Activations: 0
focus visibleunverified
Activations: 0
loadingunverified

The decision is being recorded.

Activations: 0
Component details

State coverage

Required
  • ready
  • disabled
  • focus-visible
  • loading
Verified

None

Pending
  • ready
  • disabled
  • focus-visible
  • loading

Anatomy

  • visible label
  • optional icon
  • state affordance
  • progress indicator

Token roles

  • text
  • border
  • focus
  • decision
  • risk

Implementation

Contract
action_button
Package
judgmentkit/react#ActionButton
Contract hash
65ff0e771384
Implementation hash
a658e0621bdf
Output hash
3a2f035e33d5

Contract excerpt

{
  "id": "action_button",
  "purpose": "Trigger one bounded user action",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible",
    "loading"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "disabled",
    "focus-visible",
    "loading"
  ],
  "anatomy": [
    "visible label",
    "optional icon",
    "state affordance",
    "progress indicator"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "decision",
    "risk"
  ],
  "accessibility_checks": [
    "accessible name",
    "keyboard activation",
    "focus visible",
    "target size",
    "loading exposes aria-busy",
    "every state exposes a complete, task-specific accessible name"
  ],
  "review_checks": [
    "action comes from the workflow",
    "risky actions have approval-boundary evidence",
    "the visible label is a complete, task-specific action phrase and remains on one line at every supported viewport",
    "for English copy, prefer one to four words when clarity permits; localization may use the wording needed for an unambiguous action",
    "responsive layout allocates enough width or uses shorter copy instead of wrapping, clipping, or truncating the action",
    "ready, disabled, focus-visible, and loading use semantic state and visual treatment instead of appending state metadata to the visible label",
    "loading pairs a progress indicator with a concise progress label, exposes aria-busy, and prevents repeat activation"
  ],
  "failure_signals": [
    "icon-only button has no accessible name",
    "destructive action appears without confirmation evidence",
    "visible action label wraps onto multiple lines",
    "state metadata is appended to the visible action label",
    "a truncated or clipped label hides the complete action",
    "button label overflows its container at a supported viewport"
  ]
}

Action group

Group related actions with clear priority and boundaries

readyunverified
Refund review actions
Activations: 0
disabledunverified
Refund review actions unavailable
Activations: 0
focus visibleunverified
Refund review actions
Activations: 0
Component details

State coverage

Required
  • ready
  • disabled
  • focus-visible
Verified

None

Pending
  • ready
  • disabled
  • focus-visible

Anatomy

  • primary action
  • secondary actions
  • group label or context

Token roles

  • decision
  • risk
  • border
  • spacing

Implementation

Contract
action_group
Package
judgmentkit/react#ActionGroup
Contract hash
fbe6ff6cffef
Implementation hash
a658e0621bdf
Output hash
7475477406d7

Contract excerpt

{
  "id": "action_group",
  "purpose": "Group related actions with clear priority and boundaries",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "primary action",
    "secondary actions",
    "group label or context"
  ],
  "token_bindings": [
    "decision",
    "risk",
    "border",
    "spacing"
  ],
  "accessibility_checks": [
    "logical tab order",
    "visible grouping",
    "target size"
  ],
  "review_checks": [
    "primary action is singular",
    "secondary actions remain adjacent to their object"
  ],
  "failure_signals": [
    "multiple primary actions compete",
    "actions are detached from the evidence they affect"
  ]
}

Form field

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

emptyunverified
Explain the policy basis for this decision.
Changes: 0
readyunverified
Explain the policy basis for this decision.
Changes: 0
errorunverified
Explain the policy basis for this decision.
Error: Add a reason before continuing.
Changes: 0
disabledunverified
Explain the policy basis for this decision.
Editing unlocks when receipt evidence is complete.
Changes: 0
focus visibleunverified
Explain the policy basis for this decision.
Changes: 0
Component details

State coverage

Required
  • empty
  • ready
  • error
  • disabled
  • focus-visible
Verified

None

Pending
  • empty
  • ready
  • error
  • disabled
  • focus-visible

Anatomy

  • label
  • control
  • help text
  • error text

Token roles

  • text
  • border
  • focus
  • status
  • disabled

Implementation

Contract
form_field
Package
judgmentkit/react#FormField
Contract hash
937019114f83
Implementation hash
a658e0621bdf
Output hash
0511fe38d077

Contract excerpt

{
  "id": "form_field",
  "purpose": "Collect one labeled value with help, error, and disabled affordances",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "label",
    "control",
    "help text",
    "error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "status",
    "disabled"
  ],
  "accessibility_checks": [
    "programmatic label",
    "error association",
    "instructions available"
  ],
  "review_checks": [
    "label uses domain vocabulary",
    "disabled reason is readable"
  ],
  "failure_signals": [
    "placeholder is the only label",
    "error is color-only"
  ]
}

Text field

Collect short text or numeric values

emptyunverified
Use the reference shown on the receipt.
Changes: 0
readyunverified
Use the reference shown on the receipt.
Changes: 0
errorunverified
Use the reference shown on the receipt.
Error: Enter the full reference, including RF-.
Changes: 0
disabledunverified
Use the reference shown on the receipt.
The reference is locked after review begins.
Changes: 0
focus visibleunverified
Use the reference shown on the receipt.
Changes: 0
Component details

State coverage

Required
  • empty
  • ready
  • error
  • disabled
  • focus-visible
Verified

None

Pending
  • empty
  • ready
  • error
  • disabled
  • focus-visible

Anatomy

  • label
  • input
  • help text
  • error text

Token roles

  • text
  • border
  • focus
  • status

Implementation

Contract
text_field
Package
judgmentkit/react#TextField
Contract hash
9b9f48aedec0
Implementation hash
a658e0621bdf
Output hash
c3b3c21c0c25

Contract excerpt

{
  "id": "text_field",
  "purpose": "Collect short text or numeric values",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "label",
    "input",
    "help text",
    "error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "status"
  ],
  "accessibility_checks": [
    "programmatic label",
    "input purpose when known",
    "error association"
  ],
  "review_checks": [
    "input type matches the value",
    "validation is visible and textual"
  ],
  "failure_signals": [
    "raw input replaces approved primitive",
    "invalid state lacks text feedback"
  ]
}

Text area

Collect longer written input

emptyunverified
Summarize the evidence and decision rationale.
Changes: 0
readyunverified
Summarize the evidence and decision rationale.
Changes: 0
errorunverified
Summarize the evidence and decision rationale.
Error: Add the evidence basis before continuing.
Changes: 0
disabledunverified
Summarize the evidence and decision rationale.
Notes are locked while manager review is in progress.
Changes: 0
focus visibleunverified
Summarize the evidence and decision rationale.
Changes: 0
Component details

State coverage

Required
  • empty
  • ready
  • error
  • disabled
  • focus-visible
Verified

None

Pending
  • empty
  • ready
  • error
  • disabled
  • focus-visible

Anatomy

  • label
  • multi-line control
  • help text
  • error text

Token roles

  • text
  • border
  • focus
  • spacing

Implementation

Contract
text_area
Package
judgmentkit/react#TextArea
Contract hash
66776c2fe1fd
Implementation hash
a658e0621bdf
Output hash
30ba1affaab7

Contract excerpt

{
  "id": "text_area",
  "purpose": "Collect longer written input",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "label",
    "multi-line control",
    "help text",
    "error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "spacing"
  ],
  "accessibility_checks": [
    "programmatic label",
    "resize or stable height",
    "error association"
  ],
  "review_checks": [
    "expected content is clear",
    "long content does not collapse nearby controls"
  ],
  "failure_signals": [
    "text area is used for structured choices",
    "long text overlaps following content"
  ]
}

Select field

Choose one value from a bounded option set

emptyunverified
Assign the team responsible for the next decision.
Changes: 0
readyunverified
Assign the team responsible for the next decision.
Changes: 0
errorunverified
Assign the team responsible for the next decision.
Error: Choose an owner before handoff.
Changes: 0
disabledunverified
Assign the team responsible for the next decision.
Ownership is locked after handoff begins.
Changes: 0
focus visibleunverified
Assign the team responsible for the next decision.
Changes: 0
Component details

State coverage

Required
  • empty
  • ready
  • error
  • disabled
  • focus-visible
Verified

None

Pending
  • empty
  • ready
  • error
  • disabled
  • focus-visible

Anatomy

  • label
  • trigger or native select
  • selected value
  • trailing indicator slot
  • indicator
  • options
  • help or error text

Token roles

  • text
  • border
  • focus
  • surface
  • spacing
  • density

Implementation

Contract
select_field
Package
judgmentkit/react#SelectField
Contract hash
6dcf9d595da4
Implementation hash
a658e0621bdf
Output hash
af21b3abaa8a

Contract excerpt

{
  "id": "select_field",
  "purpose": "Choose one value from a bounded option set",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "label",
    "trigger or native select",
    "selected value",
    "trailing indicator slot",
    "indicator",
    "options",
    "help or error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "surface",
    "spacing",
    "density"
  ],
  "accessibility_checks": [
    "name role value",
    "keyboard operation",
    "error association"
  ],
  "review_checks": [
    "empty option is clear when optional",
    "selected value is visible, logical-start aligned, and truncates before the trailing indicator slot",
    "custom field indicators are centered in a governed trailing slot while compact triggers use their declared compact composition",
    "native select indicators remain browser-owned unless native appearance is replaced by a declared design-system indicator"
  ],
  "failure_signals": [
    "custom select lacks keyboard evidence",
    "unassigned state is ambiguous",
    "custom field equates selected-value start padding with the chevron's physical end inset",
    "selected value overlaps or enters the trailing indicator slot",
    "field and compact select composition are conflated"
  ]
}

Checkbox group

Choose independent options from a set

readyunverified
Evidence included
Choose every source used for this decision.
Changes: 0
errorunverified
Evidence included
Choose every source used for this decision.
Error: Choose at least one evidence source.
Changes: 0
disabledunverified
Evidence included
Choose every source used for this decision.
Evidence selections are locked after approval.
Changes: 0
focus visibleunverified
Evidence included
Choose every source used for this decision.
Changes: 0
Component details

State coverage

Required
  • ready
  • error
  • disabled
  • focus-visible
Verified

None

Pending
  • ready
  • error
  • disabled
  • focus-visible

Anatomy

  • legend
  • checkbox options
  • help or error text

Token roles

  • text
  • border
  • focus
  • spacing

Implementation

Contract
checkbox_group
Package
judgmentkit/react#CheckboxGroup
Contract hash
bb7280a502ee
Implementation hash
a658e0621bdf
Output hash
822ae36eba41

Contract excerpt

{
  "id": "checkbox_group",
  "purpose": "Choose independent options from a set",
  "required_states": [
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "legend",
    "checkbox options",
    "help or error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "spacing"
  ],
  "accessibility_checks": [
    "fieldset and legend",
    "checked state",
    "keyboard operation"
  ],
  "review_checks": [
    "long labels wrap cleanly",
    "options remain independent"
  ],
  "failure_signals": [
    "checkboxes behave like radios",
    "group has no legend"
  ]
}

Radio group

Choose exactly one option from a set

emptyunverified
Refund decision
Choose one decision for this request.
Changes: 0
readyunverified
Refund decision
Choose one decision for this request.
Changes: 0
errorunverified
Refund decision
Choose one decision for this request.
Error: Choose a decision before handoff.
Changes: 0
disabledunverified
Refund decision
Choose one decision for this request.
The recorded decision cannot be changed during handoff.
Changes: 0
focus visibleunverified
Refund decision
Choose one decision for this request.
Changes: 0
Component details

State coverage

Required
  • empty
  • ready
  • error
  • disabled
  • focus-visible
Verified

None

Pending
  • empty
  • ready
  • error
  • disabled
  • focus-visible

Anatomy

  • legend
  • radio options
  • help or error text

Token roles

  • text
  • border
  • focus
  • spacing

Implementation

Contract
radio_group
Package
judgmentkit/react#RadioGroup
Contract hash
eb6f6b90e40a
Implementation hash
a658e0621bdf
Output hash
6ba76a8a7650

Contract excerpt

{
  "id": "radio_group",
  "purpose": "Choose exactly one option from a set",
  "required_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "empty",
    "ready",
    "error",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "legend",
    "radio options",
    "help or error text"
  ],
  "token_bindings": [
    "text",
    "border",
    "focus",
    "spacing"
  ],
  "accessibility_checks": [
    "fieldset and legend",
    "selected state",
    "arrow-key operation"
  ],
  "review_checks": [
    "option labels are comparable",
    "default selection is intentional"
  ],
  "failure_signals": [
    "mutually exclusive options are shown as checkboxes",
    "selected state is visual-only"
  ]
}

Toggle

Switch a binary setting on or off

readyunverified
Keep this on for policy exceptions above $250.
Changes: 0
disabledunverified
This setting is locked while approval is pending.
Changes: 0
focus visibleunverified
Keep this on for policy exceptions above $250.
Changes: 0
Component details

State coverage

Required
  • ready
  • disabled
  • focus-visible
Verified

None

Pending
  • ready
  • disabled
  • focus-visible

Anatomy

  • visible label
  • switch control
  • current state text

Token roles

  • status
  • focus
  • disabled

Implementation

Contract
toggle
Package
judgmentkit/react#Toggle
Contract hash
b73eef734a2e
Implementation hash
a658e0621bdf
Output hash
46240a49b095

Contract excerpt

{
  "id": "toggle",
  "purpose": "Switch a binary setting on or off",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "visible label",
    "switch control",
    "current state text"
  ],
  "token_bindings": [
    "status",
    "focus",
    "disabled"
  ],
  "accessibility_checks": [
    "name role value",
    "keyboard operation",
    "state text"
  ],
  "review_checks": [
    "label names the setting",
    "state change is reversible or bounded"
  ],
  "failure_signals": [
    "toggle hides the current state",
    "toggle performs a destructive action"
  ]
}

Tabs

Switch between peer sections without changing the task object

readyunverified
Receipt and policy evidence are complete.
Section changes: 0
disabledunverified
Receipt and policy evidence are complete.
Section changes: 0
focus visibleunverified
The request is within the 30-day refund window.
Section changes: 0
Component details

State coverage

Required
  • ready
  • disabled
  • focus-visible
Verified

None

Pending
  • ready
  • disabled
  • focus-visible

Anatomy

  • tab list
  • tabs
  • active tab
  • tab panels

Token roles

  • surface
  • border
  • focus
  • text

Implementation

Contract
tabs
Package
judgmentkit/react#Tabs
Contract hash
a2afae27cdd4
Implementation hash
a658e0621bdf
Output hash
36148c35e538

Contract excerpt

{
  "id": "tabs",
  "purpose": "Switch between peer sections without changing the task object",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "tab list",
    "tabs",
    "active tab",
    "tab panels"
  ],
  "token_bindings": [
    "surface",
    "border",
    "focus",
    "text"
  ],
  "accessibility_checks": [
    "tablist semantics",
    "keyboard operation",
    "active panel association"
  ],
  "review_checks": [
    "tabs are peers",
    "active state is visible"
  ],
  "failure_signals": [
    "tabs are used as a wizard",
    "inactive panels are unreachable by keyboard"
  ]
}

Dialog

Interrupt the current surface for a bounded decision or focused form

readyunverified

Confirm refund handoff

Send refund RF-1842 and its evidence to the payments team.

Dialog actions: 0
loadingunverified

Confirm refund handoff

Sending the refund handoff.

Refund RF-1842 is being sent to the payments team.

Dialog actions: 0
errorunverified

Refund handoff blocked

Keep the review open while the missing receipt is restored.

Dialog actions: 0
focus visibleunverified

Confirm refund handoff

Send refund RF-1842 and its evidence to the payments team.

Dialog actions: 0
Component details

State coverage

Required
  • ready
  • loading
  • error
  • focus-visible
Verified

None

Pending
  • ready
  • loading
  • error
  • focus-visible

Anatomy

  • title
  • body
  • dismiss action
  • primary action

Token roles

  • surface
  • border
  • focus
  • decision
  • risk

Implementation

Contract
dialog
Package
judgmentkit/react#Dialog
Contract hash
d0b0c5d298fa
Implementation hash
a658e0621bdf
Output hash
350eec717467

Contract excerpt

{
  "id": "dialog",
  "purpose": "Interrupt the current surface for a bounded decision or focused form",
  "required_states": [
    "ready",
    "loading",
    "error",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "loading",
    "error",
    "focus-visible"
  ],
  "anatomy": [
    "title",
    "body",
    "dismiss action",
    "primary action"
  ],
  "token_bindings": [
    "surface",
    "border",
    "focus",
    "decision",
    "risk"
  ],
  "accessibility_checks": [
    "dialog semantics",
    "focus management",
    "escape or dismiss",
    "no keyboard trap"
  ],
  "review_checks": [
    "primary action is visually final",
    "cancel or dismiss precedes primary action"
  ],
  "failure_signals": [
    "dialog lacks dismiss path",
    "focus is not returned after close"
  ]
}

Alert

Call attention to important status, risk, or required action

readyunverified
Activations: 0
focus visibleunverified
Activations: 0
Component details

State coverage

Required
  • ready
  • focus-visible
Verified

None

Pending
  • ready
  • focus-visible

Anatomy

  • status indicator
  • message
  • optional action

Token roles

  • status
  • risk
  • receipt
  • text

Implementation

Contract
alert
Package
judgmentkit/react#Alert
Contract hash
0dd2e0e5d500
Implementation hash
a658e0621bdf
Output hash
bee25ca21cfa

Contract excerpt

{
  "id": "alert",
  "purpose": "Call attention to important status, risk, or required action",
  "required_states": [
    "ready",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "focus-visible"
  ],
  "anatomy": [
    "status indicator",
    "message",
    "optional action"
  ],
  "token_bindings": [
    "status",
    "risk",
    "receipt",
    "text"
  ],
  "accessibility_checks": [
    "status or alert semantics",
    "non-color cue",
    "readable message"
  ],
  "review_checks": [
    "severity matches the action needed",
    "message explains next step"
  ],
  "failure_signals": [
    "color is the only severity cue",
    "alert repeats unrelated information"
  ]
}

Table

Compare structured rows and columns

emptyunverified
Refund review queue
RequestReview status
No refund requests need review.
readyunverified
Refund review queue
RequestReview statusNext action
RF-1842Needs decision
RF-1843Needs evidence
Activations: 0
loadingunverified
Refund review queue
RequestReview status
Loading current refund requests.
errorunverified
Refund review queue
RequestReview status
The refund queue could not be loaded.
focus visibleunverified
Refund review queue
RequestReview statusNext action
RF-1842Needs decision
RF-1843Needs evidence
Activations: 0
Component details

State coverage

Required
  • empty
  • ready
  • loading
  • error
  • focus-visible
Verified

None

Pending
  • empty
  • ready
  • loading
  • error
  • focus-visible

Anatomy

  • caption or heading
  • headers
  • rows
  • cells
  • empty state

Token roles

  • surface
  • border
  • text
  • spacing

Implementation

Contract
table
Package
judgmentkit/react#Table
Contract hash
5c352b7dd17f
Implementation hash
a658e0621bdf
Output hash
c839dbef6cb8

Contract excerpt

{
  "id": "table",
  "purpose": "Compare structured rows and columns",
  "required_states": [
    "empty",
    "ready",
    "loading",
    "error",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "empty",
    "ready",
    "loading",
    "error",
    "focus-visible"
  ],
  "anatomy": [
    "caption or heading",
    "headers",
    "rows",
    "cells",
    "empty state"
  ],
  "token_bindings": [
    "surface",
    "border",
    "text",
    "spacing"
  ],
  "accessibility_checks": [
    "header associations",
    "caption or label",
    "keyboard reachable controls"
  ],
  "review_checks": [
    "columns support decisions",
    "empty and loading states are clear"
  ],
  "failure_signals": [
    "fields are shown only because they exist",
    "wide table overflows without review"
  ]
}

Panel

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

readyunverified

Policy evidence

The purchase is within the 30-day refund window.
Activations: 0
loadingunverified

Policy evidence

Loading the governing policy and receipt.
errorunverified

Policy evidence

Activations: 0
Component details

State coverage

Required
  • ready
  • loading
  • error
Verified

None

Pending
  • ready
  • loading
  • error

Anatomy

  • heading
  • content region
  • optional actions

Token roles

  • surface
  • border
  • spacing
  • text

Implementation

Contract
panel
Package
judgmentkit/react#Panel
Contract hash
459196b00570
Implementation hash
a658e0621bdf
Output hash
efc4583f14b5

Contract excerpt

{
  "id": "panel",
  "purpose": "Group related work, evidence, or controls in a bounded region",
  "required_states": [
    "ready",
    "loading",
    "error"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "loading",
    "error"
  ],
  "anatomy": [
    "heading",
    "content region",
    "optional actions"
  ],
  "token_bindings": [
    "surface",
    "border",
    "spacing",
    "text"
  ],
  "accessibility_checks": [
    "heading hierarchy",
    "region label when useful",
    "responsive no overflow"
  ],
  "review_checks": [
    "panel groups one coherent concern",
    "actions are adjacent to content"
  ],
  "failure_signals": [
    "card inside card nesting creates visual clutter",
    "panel title is generic"
  ]
}

Card

Summarize one repeated item or choice

readyunverified

Refund RF-1842

Receipt and policy evidence are complete.
Submitted today
Activations: 0
disabledunverified

Refund RF-1842

Manager approval is still pending.
Submitted today
Review refund
focus visibleunverified

Refund RF-1842

Receipt and policy evidence are complete.
Submitted today
Open refund
Activations: 0
Component details

State coverage

Required
  • ready
  • disabled
  • focus-visible
Verified

None

Pending
  • ready
  • disabled
  • focus-visible

Anatomy

  • item title
  • summary
  • metadata
  • optional action

Token roles

  • surface
  • border
  • spacing
  • text

Implementation

Contract
card
Package
judgmentkit/react#Card
Contract hash
40eaf0733f40
Implementation hash
a658e0621bdf
Output hash
3d4fa17b0072

Contract excerpt

{
  "id": "card",
  "purpose": "Summarize one repeated item or choice",
  "required_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "disabled",
    "focus-visible"
  ],
  "anatomy": [
    "item title",
    "summary",
    "metadata",
    "optional action"
  ],
  "token_bindings": [
    "surface",
    "border",
    "spacing",
    "text"
  ],
  "accessibility_checks": [
    "clear heading",
    "focus target when clickable",
    "non-text contrast"
  ],
  "review_checks": [
    "card represents one object",
    "interactive area is clear"
  ],
  "failure_signals": [
    "page sections are styled as cards",
    "clickable card lacks keyboard evidence"
  ]
}

Status message

Report progress, result, validation, or completion

readyunverified
Decision recorded:Refund RF-1842 is ready for handoff.
Activations: 0
loadingunverified
Saving decision:Recording the refund decision and receipt.
errorunverified
Activations: 0
Component details

State coverage

Required
  • ready
  • loading
  • error
Verified

None

Pending
  • ready
  • loading
  • error

Anatomy

  • status text
  • severity or result
  • optional next action

Token roles

  • status
  • risk
  • receipt
  • text

Implementation

Contract
status_message
Package
judgmentkit/react#StatusMessage
Contract hash
d56c305dd570
Implementation hash
a658e0621bdf
Output hash
137d748d3d3c

Contract excerpt

{
  "id": "status_message",
  "purpose": "Report progress, result, validation, or completion",
  "required_states": [
    "ready",
    "loading",
    "error"
  ],
  "verified_states": [],
  "pending_states": [
    "ready",
    "loading",
    "error"
  ],
  "anatomy": [
    "status text",
    "severity or result",
    "optional next action"
  ],
  "token_bindings": [
    "status",
    "risk",
    "receipt",
    "text"
  ],
  "accessibility_checks": [
    "live-region behavior when async",
    "non-color cue",
    "plain-language message"
  ],
  "review_checks": [
    "message names the user-relevant result",
    "completion leaves a receipt"
  ],
  "failure_signals": [
    "spinner has no status text",
    "success state lacks receipt or next action"
  ]
}

Component guidance

When to use each component
ComponentUseStatesQuality
Action buttonTrigger one bounded user actionready, disabled, focus visible, loadingaction comes from the workflow; risky actions have approval-boundary evidence; the visible label is a complete, task-specific action phrase and remains on one line at every supported viewport; for English copy, prefer one to four words when clarity permits; localization may use the wording needed for an unambiguous action; responsive layout allocates enough width or uses shorter copy instead of wrapping, clipping, or truncating the action; ready, disabled, focus-visible, and loading use semantic state and visual treatment instead of appending state metadata to the visible label; loading pairs a progress indicator with a concise progress label, exposes aria-busy, and prevents repeat activation
Action groupGroup related actions with clear priority and boundariesready, disabled, focus visibleprimary action is singular; secondary actions remain adjacent to their object
Form fieldCollect one labeled value with help, error, and disabled affordancesempty, ready, error, disabled, focus visiblelabel uses domain vocabulary; disabled reason is readable
Text fieldCollect short text or numeric valuesempty, ready, error, disabled, focus visibleinput type matches the value; validation is visible and textual
Text areaCollect longer written inputempty, ready, error, disabled, focus visibleexpected content is clear; long content does not collapse nearby controls
Select fieldChoose one value from a bounded option setempty, ready, error, disabled, focus visibleempty option is clear when optional; selected value is visible, logical-start aligned, and truncates before the trailing indicator slot; custom field indicators are centered in a governed trailing slot while compact triggers use their declared compact composition; native select indicators remain browser-owned unless native appearance is replaced by a declared design-system indicator
Checkbox groupChoose independent options from a setready, error, disabled, focus visiblelong labels wrap cleanly; options remain independent
Radio groupChoose exactly one option from a setempty, ready, error, disabled, focus visibleoption labels are comparable; default selection is intentional
ToggleSwitch a binary setting on or offready, disabled, focus visiblelabel names the setting; state change is reversible or bounded
TabsSwitch between peer sections without changing the task objectready, disabled, focus visibletabs are peers; active state is visible
MenuReveal a compact set of contextual commandsready, disabled, focus visiblecommands are contextual; primary path remains visible
DialogInterrupt the current surface for a bounded decision or focused formready, loading, error, focus visibleprimary action is visually final; cancel or dismiss precedes primary action
AlertCall attention to important status, risk, or required actionready, focus visibleseverity matches the action needed; message explains next step
TableCompare structured rows and columnsempty, ready, loading, error, focus visiblecolumns support decisions; empty and loading states are clear
PanelGroup related work, evidence, or controls in a bounded regionready, loading, errorpanel groups one coherent concern; actions are adjacent to content
CardSummarize one repeated item or choiceready, disabled, focus visiblecard represents one object; interactive area is clear
Status messageReport progress, result, validation, or completionready, loading, errormessage names the user-relevant result; completion leaves a receipt

Quality checklist

  • Choose components by the user's task, not by the shape of the underlying data.
  • Show loading, disabled, empty, and error states with a readable explanation when they apply.
  • Keep risky decisions bounded and visibly distinct from routine actions.
  • Reuse the actual JudgmentKit component instead of recreating its appearance with one-off markup.

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.