UI composition in Screenplay
Read preferred syntax when writing or reviewing .play.
Event Modeling's wireframe step is a first-class part of the language. The shell,
the reusable shapes inside it, the forms bound to commands, and the navigation
entries other modules contribute are all declared in the .play model.
⚠️ file <Identifier> is read as a property named file, not a directive —
the type-reference shape wins the tie. file Invoices/Register.cs is a directive;
file Attachment is a property. In a trigger body the directive always wins, so
a trigger value named file is written @file.
Locate the model
Look first for the project's existing .play files: their folder is the model.
Reuse existing model/workspace roots; code-only Source/ or src/ does not
qualify. Otherwise use repository-root Screenplay/ (discovery/version gates). Never put a model under .cratis/ or hand-copy it between repositories.
cratis ai install manages .cratis/ai/, never model files. Keep explanatory
Markdown in project documentation; .play is the single flow model.
Product sources
Tool versions: toolchain SKILL.md. UI statements come from Screenplay
screens.md, outlets.md, contributions.md, navigation.md, sample-data.md, forms.md, templates.md, ui-profile.md,
fixtures/screen-release-ui.play, layout-arrangement.md, interactions.md, theme.md,
internationalization.md and file-references.md under Documentation/screenplay/. Scene
runtime sources: scaffold Scene tag, Source/JavaScript/**. See
Scene v4.82.0 runtime boundaries for
exact query registration/submission, root-profile serialization and interaction
limits. These host APIs are not new .play syntax and do not verify UI rendering.
Every construct on this page is deferred from the executable model with
information PLAY0269: it never blocks binding, and it is not evidence that a
target renders it.
The screens-release surface adds component data-context bindings,
exposed template configuration, package/icon catalogs, manual form columns, hierarchical slots,
routes, toolbars and dialog destinations, each with a separate support level
(authoring accepted, executable admitted, runtime implemented). Discover the
installed shape through MCP syntax-schema; details:
references/screen-composition-contract.md.
Absent editor highlighting is never evidence that a construct is wrong: check screenplay, not the editor (see references/screen-composition-contract.md).
Compose in this order
Decide what every screen is for before deciding how any of it is laid out. Layout work on a screen whose purpose is unsettled is rework.
- Level 1 for every screen in the flow first (
cratis-screenplay-read-surface:dataplusaction). Read the whole set, not one screen at a time. - Review the flow before adding layout. Walk it screen by screen as text
(format in
references/flow-review.md). When the host advertises the MCP-Apps extension for thescreenplayMCP server,visualize-model(aproposalIdor asketch) can also show it on a board; that is optional, and the text review is enough. Do not use the Stage sandbox as the review: it renders only part of a screen, and nothing here establishes that Stage renders an authored screen faithfully. A behavior walk of what commands change is a separate, optional check owned bycratis-stage-rendering-and-sandbox. - Add structure only to screens whose Level 1 is agreed: template, sections,
forms,
on/uses. Use Level 3 inline code last, only where Level 2 cannot say it. - Trace every field. Each
formfieldis a property of the form's command. A prefilled value comes frompopulateorfrom; a derived one fromcompose using. Eachsummaryorcolumnfield is a property of the screen's read model. A value with no origin means the command or read model is missing it: fix the slice, never invent the value in the screen. - Read before editing. Open the existing screen (or
read-workspace/declaration-detailsthrough thescreenplayMCP server) and change only the directives that were asked for. Addinglayoutmust not rewrite the Level-1 intent beneath it. - Report each screen in two or three sentences: what it shows and what the user can do. Not everyone reviewing can see a board.
Read references/worked-flow.md when a complete example is needed before composing a flow; it contains two Level-1 screens, their command, read model and form, with the field trace.
layout — the application shell
One or more per application, declared at the top level; a ui profile selects the shell with root template <Name>.
A complete example:
layout AppShell
category application
topbar
navigation panel
content page routed primary
footer
outlet Navigation of navigation in navigation
arrangement flow
column
topbar height 56
row
navigation width 240
content grow
footer height 32
Requires Screenplay 6.0 or later; migrate a Screenplay 5 model first (cratis-screenplay-modeling-lifecycle).
A slot is a region content is placed in: each plain line, optionally followed by a role (page, pane,
panel), routed [by <param>], primary and optional, in that order. An outlet is a list of items the
layout or a template offers: outlet <name> of actions|filters|tabs|stats|navigation [for item|for screen] [in <slot>].
The Screenplay 5 forms (a region outlet, destination outlet, contributes, navigation topbar|sidebar, a
feature or module toolbar) are errors PLAY0890-PLAY0896 that name the migration.
arrangement — responsive flow or pixel-precise freeform
A when width/height <class> variant replaces the entire tree for that condition, never a partial override. Read references/layout-arrangement.md when writing flow containers, freeform variants or place lines.
screen template and dialog template
Declared at module level, referenced by screens. Excerpt, inside a module:
screen template MasterDetail
fits slot content
sidebar
main
arrangement flow
row gap 16
sidebar width 280
main grow
dialog template RegisterInvoiceDialog
category Dialog
body
footer
outlet actions of actions in footer
default cancel title "Cancel" runs close
default register title "Register" emphasis primary runs submit
fits slot <name> says which slot of its parent the template fills. A dialog
template is a screen template in everything but one respect: it declares no
fits slot, because a dialog occupies no slot of the structure it opens over —
writing one is an error. Its buttons are an actions outlet (runs close|submit need no slice).
A screen fills a template by naming it and providing slot bodies; a dialog is
filled exactly the same way, because from the screen's side there is no
difference. See cratis-screenplay-read-surface for the directives that go inside.
form — bound to a command
Excerpt, inside a module; the command, query and screen are declared in its
slices.
form RegisterInvoiceForm for RegisterInvoice
populate via query GetInvoiceDefaults by customerId
field invoiceNumber label "Invoice #"
field customerId from item
field total compose using TotalCalculator
field category
choose from query AllCategories show name
on submit navigate to InvoiceList
- At most one
populate—populate via query <Query> [by <param>]orpopulate from item. field <property>takes at most one offrom <source>orcompose using <Callback>, plus an optionallabel.choose from query <Query> show <field>makes a field a picker over a list query's rows (PLAY0913). A field whose concept keys one list query's read model is a picker without it.- At most one
on submit navigate to <Screen> [by <param>], the one-line form. Any otheronin a form body is a behavior attached to the form.
⚠️ A form is discovered, not referenced. It never appears in a screen's
directive tree the way a table or summary does — it is found by its
for <Command> binding wherever that command is invoked. A form sits at module
level, so it disambiguates by module rather than by feature or slice.
The application shell: slots, outlets, hooks, blueprint references, sample data
This covers navigation outlets (topbar/sidebar, inherit/extend/override), outlets of actions, filters, tabs and stats,
contribute to, hooks and placement, alongside blueprint references and sample data.
The layout declares its navigation outlets with default items and one logo; a module, feature or screen
inherits an outlet (the default), extends it (inherited items, then its own) or overrides it (its own only).
layout AppShell
category application
content page routed primary
outlet sidebar of navigation
default sales title "Sales" target Sales
item orders title "Orders" target Sales.Orders
module Sales
outlet sidebar extends
item customers title "Customers" target Sales.Customers
feature Orders
feature Customers
contribute to <outlet>adds an entry from any module or feature, next to the screens it belongs to (navigate to <Screen> [by <param>],label,order,destination slot|dialog|external, or item lines of the outlet's kind).by <param>is a typed binding, never string interpolation.- Placement. The template offers places, the slice says which it fits, the hook picks one. A slice's screen lists
its fits in order of preference (
fits dialog, drawer, pane). A hook - abuttonnaming a State Changeslice- opens it in its first fit the page has free; writeopens dialog|drawer|in slot <name>only when this hook needs another place.runsissues the command without a form. show <Screen> by <param> from <element>.selectionin a template slot shows another screen for the selected row.
Read references/application-shell.md before writing any of it: slot roles, outlet
kinds and modes, hide/before/after, contribution resolution, the module-only target rule (PLAY0750), hooks
(runs, opens, for item|for screen, enabled when, confirm), fits and show, blueprint ranges, sample data,
MCP editing and the review checklist.
Interactions — what a click does
An interaction wires an on <thing> trigger to actions, inline or through named
behavior + uses. This is closed UI wiring, not scripting; validation stays on
the command. Trigger/action syntax is in interaction example
and guarded interactions.
Guarded alternatives and where deprecation:
guarded interactions.
Read change alternatives when a component's
on change should choose an action list by the changed item, such as a kanban move.
Read interaction example when wiring a named confirmation behavior and an inline refresh to the same screen.
State every plain and toolbar action's subject: for item (the chosen record fills its
inputs) or for screen (no row does). Omitted, the compiler infers it from types, and a
create action on a list can bind the selected row's id. Read
action subjects when adding a screen action or when
PLAY0817-PLAY0821 appear.
Scalar/named returns bind and reference-execute (ESM v7).
Renderer generation/response limits: command-surface references/generated-values-and-responses.md.
Screenplay resolves response names in form submit and execute success (Requires Screenplay 4.148.0 or later);
own failure use is PLAY0685. No ESM change; Scene runtime binding remains downstream.
An existing success continuation does not imply a response contract.
Read response continuations for scope,
precedence, PLAY0485 and examples.
- Write the one-off case inline; name it with
behaviorwhen several places need the same wiring. Ausessite must supply exactly the declared parameters (PLAY0337,PLAY0338). on/usesattach at every level —layout,module,feature, templates,form,screen,section, slot,table— and are additive: outer attachments run first unless a behavior declaresorder.on success/on failurebelong only on actions that can fail (execute,refresh,confirm,open dialog,raise);on resultonly onopen dialog. A continuation onnavigate,notify,setorclose dialogis an error (PLAY0320). Actions after an unconditionalnavigateare unreachable (PLAY0339).- Unknown commands, screens, queries, dialogs and behaviors are warnings, like
every other reference (
PLAY0330–PLAY0336). - A declared
triggeris not a UI event. Useon click, nottrigger, for a button.on <Trigger>observes an application trigger andraise <Trigger>fires one; that is where the two meet.
design system, theme and ui profile
The design system is the per-application contract; a theme implements it with values; a ui profile picks a theme, and appearance keeps only color scheme (accent, corners, font: PLAY0929). Read references/design-system-and-themes.md first.
A quoted theme name such as theme "Scene Default Light" needs Screenplay 4.227.0 (rules in the reference below).
A ui profile selects the application shell with root template (an own layout or application-scope screen template, or blueprint <B> <Name> with an optional version pin), its shell option lines, an appearance block (color scheme), the template new screens start from (new screens use template), the theme and the packages, listed in override-priority order (a later package shadows an earlier one); target platform and target size accept any identifier, so a typo is silent. The legacy layout <Name> line inside a profile still reads but warns PLAY0791: write root template. PLAY0790 to PLAY0799 check the shell. Read references/ui-profile-and-theme.md when writing a profile or fixing a shell diagnostic.
A deliverable app declares its identity, titles and labels
Symptom: a rendered app titled "Cratis Stage" whose buttons and dialogs show raw command names. The renderer defaults to those when the model is silent, so declare, in every deliverable app:
- the layout's
logo image "<path>" title "<text>"inside a navigation outlet (the application title the shell shows;logo initialsis only valid in a profile'sidentity); - a
ui profilewithroot template, shelloptionlines such asoption showFooter false, and anidentityblock (name,logo initials); - a
title "<text>"in each screen and a navigation item<id> title "<text>" target <Module.Feature>per screen; label "<text>"on everyaction.
layout AppShell
category application
content page routed primary
outlet sidebar of navigation
logo image "/assets/shop.svg" title "Shopfront"
default organizations title "Organizations" target Crm.Organizations
ui profile Desktop
target platform web
root template AppShell
option showFooter false
identity
name "Shopfront"
logo initials "SF"
screen Organizations
data OrganizationOverview[] via query AllOrganizations
title "Organizations"
action RegisterOrganization
label "New organization"
Localized strings
Localized text lives in companion .strings files and is referenced unquoted as $strings.<dotted.key>. Read references/localized-strings.md when localizing messages, labels or titles.
file — implementation or provenance, never a substitute
file is a backend attachment, a screen realization file or declaration provenance; use repository-relative paths (PLAY0264) and never let it replace the declaration. Loaded is not run. Read references/file-references.md when attaching or checking a file, or diagnosing PLAY0430–PLAY0434.
Verify
-
screenplay <model> --warnaserror(standalone) reports zero errors and zero warnings;cratis screenplay validate --warnings-as-errorssays the same when its bundled compiler matches (versions:cratis-screenplay-toolchainSKILL.md). - Every screen in the flow has Level 1 reviewed before any layout, and every form field and screen field traces to a command or read-model property.
- Every outlet a
contribute toor anoutlet <name> extendsnames is declared by a layout or template; no Screenplay 5 form (navigation topbar|sidebar,contributes, featuretoolbar, regionoutlet) remains. - Every State Change screen says what it
fits; a hook names a place only when the automatic choice is wrong. - No
dialog templatedeclaresfits slot. - Each
ui profilenames its shell withroot template, not the legacylayoutline (PLAY0791); a blueprint shell is listed underpackagesand itsversionpin is deliberate. -
packagesare ordered deliberately — later shadows earlier. - Every theme a profile selects is
compatible withone of its packages. -
target platformandtarget sizevalues are spelled correctly; nothing checks them. - A deliverable app declares layout
logo ... title, aui profilewithoptionlines andidentity, atitleper screen and alabelon everyaction. - User-visible text is
$strings.where the application is localized. - No
filereference is doing work the declaration should be doing. - Every click, submit and screen entry that does something has an
onoruses; continuations sit only on actions that can fail. - Navigation outlets, hooks, blueprint references and sample data follow
references/application-shell.md: each level's outlet mode is deliberate, no module item targets another module, every hook names a State Change slice, buttons shared by a feature's screens extend the template's actions outlet once (confirmon destructive ones), every template has acategory, and the active sample data pack is chosen once in theui profile. - Component bindings, exposed template values, manual form columns, toolbar items, outlet items and routes all trace to typed data; no runtime fallback counts as delivery. Report authoring acceptance, executable admission and runtime implementation separately.
Route near misses
- A screen's own data, actions and name resolution:
cratis-screenplay-read-surface. - Revision-checked MCP edits
cratis-screenplay-model-authoring(references/screen-authoring-workflow.md). - Application triggers and reactions:
cratis-screenplay-captures-and-reactions. - Reviewing the whole flow's design:
cratis-screenplay-model-review. - Deriving wireframes from the model (step 4):
cratis-screenplay-event-modeling. - Rendering/omissions:
cratis-stage-rendering-and-sandbox,cratis-screenplay-render-and-gap-fill. - Building the actual React application:
cratis-arc-react-page,cratis-components-styling.
Lineage
Read references/provenance.md when checking source attribution or adaptation permissions.