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`
`conversations`	Omnichannel inboxes and app activity	`inboxKey`
`knowledge`	App-specific facts, source material, and retrieval memory	`containerKey`

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'),
    },
    {
      key: 'activity',
      label: 'Activity',
      type: 'conversations',
      inboxKey: 'activity',
      allowRecordMessages: true,
    },
    {
      key: 'knowledge',
      label: 'Knowledge',
      type: 'knowledge',
      containerKey: 'business-knowledge',
      allowWrite: true,
    },
  ],
}

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.

For an inbox or message history, use the native conversations surface instead of rebuilding a chat page. See Add a conversation inbox for storage, projection, and channel-adapter guidance.

For facts and source material used by an app's AI, use the native knowledge surface. See Add app knowledge for isolation and retrieval behavior.

Declare navigation​

Choose the smallest custom surface​

Declare navigation

Choose the smallest custom surface