Components and Actions
A surface definition is a JSON-serializable object that describes a UI component tree, its data bindings, and its actions.
Surface definition shape
The UISurfaceDefinition object has four main fields:
{
schema: 'kit.ui/v1',
root: 'layout',
components: [
// Array of component objects
],
form: {
// Optional form definition for wait surfaces
}
}
schema: Must be exactly'kit.ui/v1'.root: The ID of the top-level component in thecomponentsarray.components: A flat array of component objects. Components reference their children by ID.form: An optional form definition, valid only onwaitsurfaces.
Resource and component IDs
The platform enforces strict naming rules for surfaces and their components:
- Surface ID: Must match
^[a-z0-9][a-z0-9-]{0,62}$(kebab-case, up to 63 characters). - Component ID: Must match
^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$(alphanumeric with dots, underscores, or hyphens, up to 128 characters).
Component reference
Layout components
Layout components organize other components on the screen.
Card
Bordered container with an optional header and status.
- Children:
single - Props:
dense(boolean; literal): Use tighter body padding.map(object; literal): Map known displayed values to labels.status(any; bindable): Status value used to derive the header pill.statusLabel(any; bindable): Header status label.statusTone(string; literal; values:"neutral" | "info" | "success" | "warning" | "error"): Forced status tone.subtitle(string; bindable): Header subtitle.title(string; bindable): Header title.transform(string; literal; values:"capitalize" | "title" | "upper" | "lower" | "humanize"): Status label transform.
Divider
Horizontal rule between content blocks.
- Children:
none - Props: None.
Form
Groups wait-surface inputs and actions.
- Children:
list - Props:
title(string; bindable): Form heading.
Grid
Responsive equal-width columns.
- Children:
list - Props:
columns(number; literal; values:1 | 2 | 3 | 4; integer): Column count.gap(string; literal; values:"xs" | "sm" | "md" | "lg"): Spacing between children.
Row
Wrapping horizontal group.
- Children:
list - Props:
align(string; literal; values:"start" | "center" | "end" | "baseline"): Cross-axis alignment.gap(string; literal; values:"xs" | "sm" | "md" | "lg"): Spacing between children.justify(string; literal; values:"between"): Set to between to push children apart.
Section
Labelled group with one child.
- Children:
single - Props:
collapsible(boolean; literal): Allow the section to be folded.defaultOpen(boolean; literal): Initial collapsible state.description(string; bindable): Section description.title(string; bindable): Section label.
Stack
Vertical stack and the default surface container.
- Children:
list - Props:
gap(string; literal; values:"xs" | "sm" | "md" | "lg"): Spacing between children.
Display components
Display components render data to the user.
Avatar
Initials derived from a name or email.
- Children:
none - Props:
email(string; bindable): Fallback source for initials.label(string; bindable): Text beside the avatar.name(string; bindable): Name used for initials.size(string; literal; values:"sm" | "md" | "lg"): Avatar size.
Badge
Small label with an explicit tone.
- Children:
none - Props:
format(string; literal; values:"text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean"): Display format.maxChars(number; literal; integer; min 1): Maximum displayed characters.text(any; bindable): Badge label.tone(string; literal; values:"neutral" | "info" | "success" | "warning" | "error"): Badge tone.transform(string; literal; values:"capitalize" | "title" | "upper" | "lower" | "humanize"): Text transform.
Code
Monospace text block.
- Children:
none - Limits: 20,000 characters.
- Props:
label(string; bindable): Block label.text(any; bindable): Code or payload.wrap(boolean; literal): Wrap long lines.
DiffView
Structural JSON or line-by-line text comparison.
- Children:
none - Limits: Depth 6, children 100, lines 2,000, characters 200,000.
- Props:
after(any; bindable): Proposed value.before(any; bindable): Prior value.mode(string; literal; values:"json" | "text"): Comparison mode.
Duration
A duration in milliseconds or between two instants.
- Children:
none - Props:
end(union; bindable): End instant (string or number).size(string; literal; values:"xs" | "sm" | "md" | "lg"): Displayed value size.start(union; bindable): Start instant (string or number).tone(string; literal; values:"default" | "muted" | "success" | "warning" | "error" | "info"): Displayed value tone.unit(string; literal; values:"seconds" | "ms"): Numeric instant unit.value(number; bindable; min 0): Duration in milliseconds.
EmailMessageCard
Inbox list or opened email message.
- Children:
none - Limits: 50 renderedMessages.
- Props:
body(string; bindable): Message body.cc(string; bindable): Carbon-copy recipients.date(union; bindable): Sent or received instant (string or number).emptyText(string; bindable): Empty-state text.fields(object; literal): Field-name mapping.from(string; bindable): Sender.labels(array; bindable): Message labels (items: string).message(object; bindable): Single message.messages(array; bindable): Message list (items: object).snippet(string; bindable): Preview text.subject(string; bindable): Subject.to(string; bindable): Recipients.unread(boolean; bindable): Unread state.
FileChip
Metadata and download affordance for a produced file.
- Children:
none - Interaction:
single-action - Props:
file(object; bindable): Binary descriptor.downloadUrl(string; literal): Protected download URL.fileName(string; literal): Original file name.key(string; literal; required): Binary property key.mimeType(string; literal): MIME type.size(number; literal; min 0): File size in bytes.
label(string; bindable): Displayed file name.
Heading
A section title.
- Children:
none - Props:
level(number; literal; values:1 | 2 | 3; integer): Heading level.maxChars(number; literal; integer; min 1): Maximum displayed characters.text(any; bindable): Heading text.transform(string; literal; values:"capitalize" | "title" | "upper" | "lower" | "humanize"): Text transform.
HtmlRenderer
Sandboxed HTML fragment renderer.
- Children:
none - Limits: 20,000 characters, height 80–1200.
- Props:
allowRemoteImages(boolean; literal): Allow remote HTTPS images.emptyText(string; bindable): Empty-state text.height(number; literal; min 80; max 1200): Frame height in pixels.html(string; bindable): HTML markup.label(string; bindable): Frame label.
JsonInspector
Collapsible JSON tree and default fallback renderer.
- Children:
none - Props:
collapsed(boolean; literal): Start collapsed.value(any; bindable): Any JSON value.
KeyValue
Declared label/value entries or a bound object.
- Children:
none - Props:
columns(number; literal; values:1 | 2; integer): Pairs per row.dense(boolean; literal): Use tighter row spacing.emptyText(string; bindable): Empty-state text.entries(array; bindable): Declared label/value entries.- Items: object; literal
currency(string; literal): ISO 4217 currency code.decimals(number; literal; integer; min 0; max 20): Fixed decimal places.format(string; literal; values:"text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean"): Display format.label(string; bindable): Row label.map(object; literal): Map known displayed values to labels.maxChars(number; literal; integer; min 1): Maximum displayed characters.mono(boolean; literal): Render the value in monospace.tone(string; literal; values:"default" | "muted" | "success" | "warning" | "error" | "info"): Displayed value tone.transform(string; literal; values:"capitalize" | "title" | "upper" | "lower" | "humanize"): Text transform.type(string; literal; values:"status"): Set to status to render a status pill.unit(string; literal; values:"seconds" | "ms"): Numeric timestamp unit.value(any; bindable): Row value.
- Items: object; literal
hideEmpty(boolean; literal): Hide missing values.humanizeKeys(boolean; literal): Humanize object keys.mono(boolean; literal): Render shorthand values in monospace.value(object; bindable): Object whose keys become labels.
Money
A formatted currency amount.
- Children:
none - Props:
currency(string; bindable): ISO 4217 currency code.decimals(number; literal; integer; min 0; max 20): Fixed decimal places.signed(boolean; literal): Colour positive and negative values.size(string; literal; values:"xs" | "sm" | "md" | "lg"): Displayed value size.tone(string; literal; values:"default" | "muted" | "success" | "warning" | "error" | "info"): Displayed value tone.value(number; bindable): Currency amount.
Stat
One prominent value with a label and caption.
- Children:
none - Props:
caption(any; bindable): Caption below the value.captionTransform(string; literal; values:"capitalize" | "title" | "upper" | "lower" | "humanize"): Caption transform.currency(string; literal): ISO 4217 currency code.decimals(number; literal; integer; min 0; max 20): Fixed decimal places.format(string; literal; values:"text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean"): Display format.label(string; bindable): Label above the value.maxChars(number; literal; integer; min 1): Maximum displayed characters.mono(boolean; literal): Render the value in monospace.tone(string; literal; values:"default" | "muted" | "success" | "warning" | "error" | "info"): Displayed value tone.transform(string; literal; values:"capitalize" | "title" | "upper" | "lower" | "humanize"): Text transform.unit(string; literal; values:"seconds" | "ms"): Numeric timestamp unit.value(any; bindable): Displayed value.
StatusPill
Semantic status pill for statuses, booleans, and HTTP codes.
- Children:
none - Props:
format(string; literal; values:"text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean"): Display format.label(any; bindable): Displayed label.maxChars(number; literal; integer; min 1): Maximum displayed characters.status(any; bindable): Status value.tone(string; literal; values:"neutral" | "info" | "success" | "warning" | "error"): Forced tone.transform(string; literal; values:"capitalize" | "title" | "upper" | "lower" | "humanize"): Text transform.
Table
Tabular view of an array.
- Children:
none - Limits: 100 renderedRows.
- Props:
columns(array; literal): Literal field names or column definitions.- Items: union; literal (string or object).
align(string; literal; values:"left" | "center" | "right"): Cell alignment.currency(string; literal): ISO 4217 currency code.decimals(number; literal; integer; min 0; max 20): Fixed decimal places.format(string; literal; values:"text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean"): Display format.header(string; literal): Column heading.key(string; literal; required): Field name inside each row.map(object; literal): Map known displayed values to labels.maxChars(number; literal; integer; min 1): Maximum displayed characters.mono(boolean; literal): Render cells in monospace.tone(string; literal; values:"default" | "muted" | "success" | "warning" | "error" | "info"): Displayed value tone.transform(string; literal; values:"capitalize" | "title" | "upper" | "lower" | "humanize"): Text transform.type(string; literal; values:"status"): Set to status to render status pills.unit(string; literal; values:"seconds" | "ms"): Numeric timestamp unit.
- Items: union; literal (string or object).
dense(boolean; literal): Use tighter rows.emptyText(string; bindable): Empty-state text.items(array; bindable): Rows to render.
Text
Body text with shared formatting.
- Children:
none - Props:
currency(string; literal): ISO 4217 currency code.decimals(number; literal; integer; min 0; max 20): Fixed decimal places.format(string; literal; values:"text" | "number" | "compact" | "percent" | "currency" | "bytes" | "duration" | "date" | "datetime" | "time" | "list" | "json" | "boolean"): Display format.maxChars(number; literal; integer; min 1): Maximum displayed characters.mono(boolean; literal): Render in monospace.muted(boolean; literal): Shorthand for the muted tone.size(string; literal; values:"xs" | "sm" | "md" | "lg"): Displayed value size.text(any; bindable): Value to display.tone(string; literal; values:"default" | "muted" | "success" | "warning" | "error" | "info"): Displayed value tone.transform(string; literal; values:"capitalize" | "title" | "upper" | "lower" | "humanize"): Text transform.unit(string; literal; values:"seconds" | "ms"): Numeric timestamp unit.weight(string; literal; values:"normal" | "medium" | "semibold"): Font weight.
Timestamp
ISO or epoch timestamp.
- Children:
none - Props:
format(string; literal; values:"datetime" | "date" | "time" | "smart"): Timestamp format.relative(boolean; literal): Display relative time.size(string; literal; values:"xs" | "sm" | "md" | "lg"): Displayed value size.tone(string; literal; values:"default" | "muted" | "success" | "warning" | "error" | "info"): Displayed value tone.unit(string; literal; values:"seconds" | "ms"): Numeric timestamp unit.value(union; bindable): ISO string or epoch number.
Input and action components
Input components collect data from the user, and action components trigger events.
ApproveRejectBar
Named approve/reject decision actions.
- Children:
none - Interaction:
multi-action - Actions:
approve,reject. - Props:
approveLabel(string; bindable): Approve button label.canDecide(boolean; bindable): Whether the viewer may decide.comment(string; bindable): Current comment value.commentRequired(boolean; bindable): Require a comment before rejection.decidedBy(string; bindable): Recorded decider.decision(string; bindable): Recorded decision.disabledReason(string; bindable): Reason actions are disabled.rejectLabel(string; bindable): Reject button label.
Button
Single-action button.
- Children:
none - Interaction:
single-action - Actions:
default. - Props:
disabled(boolean; bindable): Disabled state.label(string; bindable): Button label.variant(string; literal; values:"primary" | "default" | "danger"): Button variant.
Checkbox
Boolean form input.
- Children:
none - Interaction:
input - Props:
description(string; bindable): Helper text.disabled(boolean; bindable): Disabled state.label(string; bindable): Text beside the checkbox.
Select
Single-choice form input.
- Children:
none - Interaction:
input - Props:
disabled(boolean; bindable): Disabled state.label(string; bindable): Field label.options(array; bindable): Literal or bound options.- Items: union; literal (string, number, or object).
label(string; literal): Displayed option label.value(union; literal; required): Submitted option value (string or number).
- Items: union; literal (string, number, or object).
placeholder(string; bindable): Placeholder.
TextArea
Multi-line form input.
- Children:
none - Interaction:
input - Props:
disabled(boolean; bindable): Disabled state.label(string; bindable): Field label.placeholder(string; bindable): Placeholder.rows(number; literal; integer; min 1): Visible rows.
TextField
Single-line text input.
- Children:
none - Interaction:
input - Props:
disabled(boolean; bindable): Disabled state.label(string; bindable): Field label.placeholder(string; bindable): Placeholder.type(string; literal; values:"text" | "number" | "email" | "url"): HTML input type.
Reserved component types
The following component types are reserved for internal platform use and are rejected by validation if used in a custom surface:
Accordion, AgentRunPanel, CalendarEventCard, DatePicker, ErrorPanel, Icon, Image, List, Markdown, ProgressBar, RadioGroup, SlackMessageCard, SlackThread, Spacer, Spinner, Tabs, Timeline, ToolCallCard, Tree.
Static and dynamic props
Component props can be static literal values or dynamic data bindings.
// Static prop
{
id: 'title',
type: 'Heading',
props: {
text: 'Customer Details',
},
}
// Dynamic prop
{
id: 'amount',
type: 'Money',
props: {
value: {
path: '/$output/Process Payment/main/0/0/amount',
},
currency: 'USD', // Static prop mixed with dynamic
},
}
Actions
Actions define what happens when a user interacts with a component.
ButtonandFileChipsupport a single action nameddefault.FileChiprequiresactions.defaultas anavigateaction whosehrefbinds to the binary descriptor'sdownloadUrl(/$binary/<step>/main/0/0/<key>/downloadUrl) to render a clickable download button.ApproveRejectBarsupports two actions:approveandreject.
The available action types depend on the surface slot:
- Output surfaces: Only support the
navigateaction (e.g., opening a URL). - Wait surfaces: Support
navigate,node.resume, andnode.stop.
actions: {
approve: {
type: 'node.resume',
payload: {
comment: { path: '/$form/comment', default: '' },
},
},
reject: {
type: 'node.stop',
payload: {
reason: { path: '/$form/comment', default: 'Rejected by reviewer' },
},
},
}
Forms and validation rules
Wait surfaces can define a form to collect user input. Input components (TextField, TextArea, Select, Checkbox) bind to these fields using the /$form/<field> path.
Surface form fields
Every field in form.fields requires name, label, and type.
- Types:
'text' | 'textarea' | 'number' | 'email' | 'url' | 'checkbox' | 'select' | 'file'. - Required: Optional
required?: boolean. - Default: Non-
filefields accept an optionaldefault?: SurfaceBinding. - Select: Requires a non-empty
options: Array<{ label: string, value: string }>. - File: Supports
accept?: string[](MIME types),multiple?: boolean,maxFiles?: number(1–5), andmaxBytes?: number(up to 10 MiB / 10,485,760 bytes).filefields CANNOT have adefaultbinding.
General validation rules
The platform strictly validates surface definitions during culvii dev and culvii deploy:
- Schema: Must be
kit.ui/v1. - Size: The serialized definition cannot exceed 256 KiB.
- Component count: Must contain between 1 and 300 components.
- Depth: The component tree cannot exceed a depth of 12 levels.
- Reachability: Every component in the
componentsarray must be reachable from theroot, and all IDs must be unique. - Props: Props are validated against the specific component's schema.
- Bindings: Data binding paths must start with
/$output,/$input,/$exec, or/$binary./$formis only allowed in wait surfaces.