Surfaces & Screens

Surfaces define interaction boundaries between users, systems, and the product. They are platform-agnostic - describing structure and behavior, not visual layout. Surfaces connect to entities through bindings and to workflows through actions and hooks.

Surface Kinds

Kind	Purpose	Use Case
view	Read-only data display	Lists, detail pages, reports
form	Data input with validation	Create/edit forms, settings
dashboard	Aggregated metrics and widgets	Admin panels, analytics
page	Full page layout	Landing pages, multi-section views
modal	Overlay dialog	Confirmations, quick edits
component	Reusable UI fragment	Shared widgets, cards

View Surface

billing.prd

surface invoice_list {
  kind: view
  title: billing.invoice_strings.invoice_list_title
  binds: invoice

  actions: [create_invoice, open_invoice]

  hooks {
    load: load_invoices
  }

  surfaces: [filter_bar, invoice_table]
}

Form Surface

surface invoice_form {
  kind: form
  binds: invoice

  fields {
    customer { required: true }
    total { required: true }
    notes { required: false }
  }

  rules: [customer_required, total_positive]

  hooks {
    submit: create_invoice
    change: validate_invoice
  }

  actions: [submit_invoice, cancel]
}

Dashboard Surface

surface billing_dashboard {
  kind: dashboard
  title: "Billing Overview"
  capability: billing_management

  surfaces: [
    revenue_chart,
    outstanding_invoices,
    recent_payments,
    overdue_alerts
  ]

  hooks {
    load: load_dashboard_data
  }
}

Key Properties

binds - Data binding to an entity. The surface displays or collects data for this entity.
actions - Workflow entry points available from this surface (e.g., buttons, links).
hooks - Lifecycle behavior: load (on open), submit (on form submit), change (on field change).
surfaces - Nested sub-surfaces for composition. Build complex UIs from smaller pieces.
fields - For form surfaces: the list of input fields.
rules - Validation rules applied to this surface's data.

Rendering & Design Tokens

Surfaces describe what is shown. Renderings and design tokens describe how it looks. Use rendering blocks to define layout, grid, and styles. Use tokens to define colors, spacing, typography, and breakpoints.

tokens billing_tokens {
  color {
    brand_primary: "#6366F1"
    surface_background: "#F3F4F6"
    danger: "#EF4444"
  }

  spacing {
    sm: 8
    md: 16
    lg: 24
  }

  breakpoint {
    sm: 480
    md: 768
    lg: 1024
  }
}

rendering invoice_list_rendering {
  target: invoice_list

  layout { direction: vertical; gap: md }
  style { padding: lg }
}

Localization

Surface titles and labels can reference strings blocks for full localization support:

strings invoice_strings {
  invoice_list_title: "Invoices"
  create_button: "New Invoice"
  total_label: "Total Amount"
  customer_required: "Customer is required"
}