> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/the-building-blocks/screens-and-blueprint.md).

# Blueprint, Design & Screens

The blueprint is the high-level screen plan for a Buzzy app. Design is where those planned screens become real screen-level layouts, bindings, actions, and widgets. Screens are the runtime surfaces users interact with.

Use this page to understand how screens pull data from datatables, render forms and views, pass row context, and connect the app together.

## Blueprint vs Design vs Screens

| Artifact         | Purpose                                                                                                                        | Why it matters                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Blueprint        | Defines the intended screens, navigation, major screen families, and screen roles before detailed layout work starts.          | It is the last cheap place to check whether the app has the right high-level surfaces.               |
| Design           | Screen-level editing and generation surface for layouts, components, data bindings, actions, widgets, and responsive behavior. | It turns the blueprint into usable screens that pull the right data and support the right workflows. |
| Screen resources | Persisted screens with real IDs, layouts, bindings, actions, and settings.                                                     | Runtime navigation, screen settings, and tests need real screen IDs.                                 |
| Screen settings  | App-level wiring such as home screen, public screens, sign-in screens, and other navigation entry points.                      | The runtime needs to know where users start and which screens are public.                            |

In Builder MCP workflows, the usual order is:

1. Review the accepted brief, flows, data model, and theme.
2. Generate or adapt the blueprint.
3. Ensure screens from the blueprint so the planned screen names become real screen resources.
4. Update app screen settings using the real screen IDs.
5. Build or refine detailed screen layouts.
6. Verify bindings, actions, tests, and preview behavior.

## High-Level Blueprint

The blueprint should answer the structural questions before detailed screen editing begins:

* What are the main public, authenticated, admin, and role-specific screens?
* Which screens are list, detail, create, edit, dashboard, onboarding, confirmation, modal, or settings surfaces?
* Which screens need persistent navigation such as header, footer, side panel, or left navigation?
* Which screens pass row context to other screens?
* Which destructive or submit workflows need confirmation screens?
* Which screens should be public, and which require sign-in?

```mermaid
flowchart TD
    H["Home / Dashboard"] --> L["Bookings List"]
    L --> D["Booking Detail"]
    D --> E["Edit Booking"]
    D --> C["Cancel Booking Confirmation"]
    H --> P["Properties"]
    P --> PD["Property Detail"]
    H --> A["Admin Settings"]
```

The blueprint does not need every text label or card layout. It needs enough structure that the app has the right screens, navigation, role coverage, and workflow endpoints.

## Screen-Level Design

The Design surface is where each screen becomes concrete.

Screen-level design decides:

* which toolkit layout or shell a screen uses
* which datatable each view, form, filter, or widget reads from
* which fields appear in summary, read, edit, insert, or filter mode
* how repeated rows render as cards, table rows, lists, dashboards, maps, calendars, or custom panels
* which actions submit, navigate, delete, update fields, run functions, or run agents
* how widgets are embedded and configured
* how the screen behaves across desktop, tablet, and mobile contexts

Blueprint is about screen architecture. Design is about making each screen work.

## What a Screen Contains

A Buzzy screen is a tree of layout nodes, components, fields, text, media, icons, actions, visibility rules, and optional widgets.

```mermaid
flowchart TD
    A["Screen"] --> B["Layout Structure<br/>sections, grids, containers, shells"]
    A --> C["Components"]
    C --> C1["View<br/>query rows"]
    C --> C2["Form<br/>capture/read/edit"]
    C --> C3["Filter<br/>provide filter context"]
    A --> D["Fields<br/>summary/read/edit/insert/filter"]
    A --> E["Actions<br/>navigate, submit, delete, update field, run function"]
    A --> F["Widgets<br/>native widgets or code widgets"]
    A --> G["Visibility Rules<br/>show/hide based on context"]
```

## Views

A view component reads rows from a datatable and renders them through a repeated layout. Views are used for lists, tables, cards, dashboards, search results, calendars, maps, and many reporting surfaces.

A view usually needs:

* a selected datatable
* filters or a filter context when the results should be narrowed
* sorting and paging settings where relevant
* a results layout with one repeated row/card/table item
* a no-results layout for empty states

```mermaid
flowchart LR
    T["Datatable"] --> Q["View Query<br/>filters, sort, paging"]
    Q --> R["Rows"]
    R --> L["Repeated Layout"]
    L --> U["Rendered list, table, cards, map, or dashboard"]
```

Use a normal view for independent row queries. For parent-scoped child rows, use the real sub-table field pattern where the data model declares a parent-child relationship.

## Forms and Fields

A form component provides row context for fields. It can be used in:

* **capture** mode to create a row
* **read** mode to display a row
* **edit** mode to update a row

Field nodes render actual fields from the data model. The same field can appear differently depending on mode:

| Field mode | Typical use                                       |
| ---------- | ------------------------------------------------- |
| Insert     | Collect a value before creating a row.            |
| Read       | Show a value in a form/detail context.            |
| Edit       | Let an allowed user update a value.               |
| Summary    | Show compact display in cards, lists, or headers. |
| Filter     | Capture filter input for a filter component.      |

## Row Context

Many screens need to know which row they are working with.

```mermaid
flowchart TD
    L["List Screen<br/>view over Booking rows"] -->|user opens one booking| D["Booking Detail Screen<br/>receives current booking row"]
    D -->|sub-table context| P["Payments<br/>child rows where embeddingRowID = booking row ID"]
    D -->|edit action| E["Edit Booking Screen<br/>same booking row context"]
```

Common context sources include:

* a view repeated row
* a screen opened from a selected row
* a form that is editing or reading a row
* a parent row for sub-table children
* a filter context consumed by a view

When fields or sub-tables appear outside the context they need, the Debug panel can surface errors such as missing row context, invalid table reference, invalid field reference, or sub-table context mismatch.

## Actions

Actions make a screen interactive. Common actions include:

* navigate to another screen
* pass the current row, parent row, or no row
* submit a capture form
* delete a row
* update a field
* filter or clear a filter
* run a Buzzy Function
* run an agent
* authenticate, register, reset password, or log out

Navigation actions should target real persisted screen IDs, not guessed screen names. This is why blueprint screens are ensured before detailed navigation and tests are finalized.

## Widgets

Use widgets when a screen needs richer interaction than standard forms, fields, views, and filters provide.

Examples include:

* map or calendar experiences
* galleries and file managers
* dashboard panels and charts
* booking or availability panels
* custom controls backed by the Async API
* reusable native widget patterns

Code widgets run inside a browser/webview sandbox and can use the [Async API + React HTML Components](/the-building-blocks/code-widget-custom-code/new-async-api-+-react-html-components.md) to read and update app data through the current user context. Keep secrets and privileged provider calls in [Buzzy Functions & Constants](/the-building-blocks/buzzy-functions-and-constants.md), not in widget code.

## Debugging Screens

Use the [In-App Debugging](/troubleshooting/in-app-debugging.md) when a screen does not behave as expected.

Common problems include:

* a view or form has no datatable selected
* a field points to a missing or wrong field ID
* a field is outside the view/form/row context it needs
* a sub-table is not inside its parent row context
* a filter context is not consumed by the intended view
* an action points to a missing screen
* submit or filter actions are outside the component that owns them

Fix errors first, then review warnings, then use informational debug output to understand runtime context.

## Related Pages

* [Buzzy Datamodel Overview](/the-building-blocks/datatables-fields-and-data/buzzy-datamodel-overview.md)
* [Themes](/the-building-blocks/themes.md)
* [Toolkits, Cookbooks & Widgets](/the-building-blocks/toolkits-and-cookbooks.md)
* [Code widget](/the-building-blocks/code-widget-custom-code.md)
* [In-App Debugging](/troubleshooting/in-app-debugging.md)