Skip to main content

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 the components array.
  • components: A flat array of component objects. Components reference their children by ID.
  • form: An optional form definition, valid only on wait surfaces.

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.
    • 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.
    • 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).
    • 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.

  • Button and FileChip support a single action named default. FileChip requires actions.default as a navigate action whose href binds to the binary descriptor's downloadUrl (/$binary/<step>/main/0/0/<key>/downloadUrl) to render a clickable download button.
  • ApproveRejectBar supports two actions: approve and reject.

The available action types depend on the surface slot:

  • Output surfaces: Only support the navigate action (e.g., opening a URL).
  • Wait surfaces: Support navigate, node.resume, and node.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-file fields accept an optional default?: SurfaceBinding.
  • Select: Requires a non-empty options: Array<{ label: string, value: string }>.
  • File: Supports accept?: string[] (MIME types), multiple?: boolean, maxFiles?: number (1–5), and maxBytes?: number (up to 10 MiB / 10,485,760 bytes). file fields CANNOT have a default binding.

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 components array must be reachable from the root, 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. /$form is only allowed in wait surfaces.