Compose app surfaces

Surfaces are the pages shown in an installed app's navigation. They let you present a cohesive product while reusing mature TWL Tool experiences.

Type	Use it for	Required binding
frontendPage	A custom overview, dashboard, or guided UI	page
dataWorkspaceView	Records, saved content, and app data	table; optional viewKey
document	A document or a folder of documents	exactly one of document, documentFolder
chat	AI chat constrained to one app workflow	preset.workflow
contentScheduler	Scheduling documents from an app	optional documentFolder and space

Declare navigation

ui: {
  icon: 'sparkles',
  color: '#6574f7',
  defaultSurface: 'overview',
  surfaces: [
    {
      key: 'overview',
      label: 'Overview',
      type: 'frontendPage',
      page: ref('frontendPages', 'overview'),
    },
    {
      key: 'inspiration',
      label: 'Inspiration',
      type: 'dataWorkspaceView',
      table: ref('dataWorkspaceTables', 'inspiration'),
      viewKey: 'gallery',
    },
    {
      key: 'drafts',
      label: 'Drafts',
      type: 'document',
      documentFolder: ref('documentFolders', 'drafts'),
    },
  ],
}

If surfaces exist and defaultSurface is omitted, defineApp() selects the first surface.

Choose the smallest custom surface

A custom page is ideal for product-specific composition. Once a user enters a specialized task, navigate to the native surface that already owns the behavior. This preserves accessibility, permissions, updates, and consistent data handling across TWL Tool.