UI Layouts

Layouts are JSON files that define how an entity’s edit and view pages are structured in the UI. They control which fields appear in which sections, how tabs are organized, and where component blocks (assets panel, relationship graph, timeline, etc.) are placed.

Without a layout file, StudioBrain auto-generates a default form from the template’s field list. With a layout file, you get full control over the page structure.

Where Layouts Live

Layout files are stored in _Templates/Layouts/ and follow the naming convention {entity_type}.layout.json:

_Templates/Layouts/
  character.layout.json
  location.layout.json
  biome.layout.json
  recipe.layout.json

CatalogSync provides default layouts from the studiobrain-templates catalog repo in the templates/Layouts/ directory. These are discovered alongside templates during catalog sync.

Layout Structure

A layout file is a JSON object with sections and optional tabs:

{
  "entity_type": "character",
  "sections": [
    {
      "id": "identity",
      "label": "Identity",
      "tab": "overview",
      "fields": ["name", "display_name", "age", "species", "faction"]
    },
    {
      "id": "appearance",
      "label": "Appearance",
      "tab": "overview",
      "fields": ["physical_description", "distinguishing_features"],
      "component": "primary-image"
    },
    {
      "id": "personality",
      "label": "Personality & Traits",
      "tab": "details",
      "fields": ["traits", "motivations", "fears", "speech_patterns"]
    },
    {
      "id": "backstory",
      "label": "Backstory",
      "tab": "details",
      "fields": ["backstory", "key_events"],
      "component": "markdown-content"
    },
    {
      "id": "relationships",
      "label": "Relationships",
      "tab": "relations",
      "component": "entity-relationships"
    },
    {
      "id": "assets",
      "label": "Assets",
      "tab": "assets",
      "component": "entity-assets"
    }
  ],
  "tabs": [
    { "id": "overview", "label": "Overview" },
    { "id": "details", "label": "Details" },
    { "id": "relations", "label": "Relations" },
    { "id": "assets", "label": "Assets" }
  ]
}

Sections

Each section represents a visual block on the entity page. A section can contain form fields, a component block, or both.

Component Blocks

Component blocks are reusable UI widgets that render specialized content beyond simple form fields. The built-in blocks are:

Plugin blocks use the format plugin:{pluginId}:{panelId} and are available when the corresponding plugin is installed.

Tabs

The tabs array defines the tab bar at the top of the entity page. Each tab has:

If no tabs array is provided, StudioBrain falls back to six default tabs: Overview, Details, Relations, Assets, Timeline, and AI.

Sections are assigned to tabs via their tab field. A section without a tab value appears on every tab.

Resolution Order

When rendering an entity page, StudioBrain resolves the layout through these layers:

The first layout found is used. There is no merging between layers — the winning layout defines the entire page structure.

The Layout Designer

StudioBrain includes a visual Layout Designer accessible from Settings > Templates > Layout Designer. It provides a drag-and-drop interface for building layouts without editing JSON:

• Add, remove, and reorder sections
• Assign fields to sections by dragging from the field palette
• Insert component blocks from the component palette
• Create and configure tabs
• Preview the layout in real time
• Export the layout as a .layout.json file

The Layout Designer saves layouts to _Templates/Layouts/ (or to the database on Cloud).

Creating a Layout Manually

If you prefer editing JSON directly:

1. Create _Templates/Layouts/{entity_type}.layout.json.
2. Define your sections and tabs.
3. Reference field names from the entity’s template.
4. Save. The layout takes effect immediately for all entities of that type.

Example: Recipe Layout

{
  "entity_type": "recipe",
  "sections": [
    {
      "id": "basics",
      "label": "Recipe Info",
      "tab": "overview",
      "fields": ["name", "cuisine", "dish_type", "prep_time", "cook_time", "servings"]
    },
    {
      "id": "hero_image",
      "label": "Hero Image",
      "tab": "overview",
      "component": "primary-image"
    },
    {
      "id": "ingredients",
      "label": "Ingredients",
      "tab": "recipe",
      "fields": ["ingredients"]
    },
    {
      "id": "steps",
      "label": "Steps",
      "tab": "recipe",
      "fields": ["steps"],
      "component": "markdown-content"
    },
    {
      "id": "notes",
      "label": "Chef's Notes",
      "tab": "recipe",
      "fields": ["notes", "tips", "variations"]
    },
    {
      "id": "media",
      "label": "Photos & Videos",
      "tab": "media",
      "component": "entity-assets"
    }
  ],
  "tabs": [
    { "id": "overview", "label": "Overview" },
    { "id": "recipe", "label": "Recipe" },
    { "id": "media", "label": "Media" }
  ]
}

Layout-Driven View Pages

By default, entity view pages (the read-only detail page) use a hand-coded layout. To opt into layout-driven rendering for view pages as well, add a view_config section to the layout:

{
  "entity_type": "character",
  "view_config": {
    "layout_driven": true
  },
  "sections": [ ... ],
  "tabs": [ ... ]
}

When layout_driven is true, the view page uses the same section and tab structure as the edit page. If the layout cannot be loaded or layout_driven is false, StudioBrain automatically falls back to the legacy hand-coded view page.

Next Steps

• Template System Overview — What templates are and how they work
• Template Packs — Bundled templates, rules, and layouts
• Inheritance & Overrides — How resolution layers work