Screen

Definition & Purpose

A Screen represents a primary user-facing surface or viewport where an actor can view status or initiate actions. It serves as the top-level container node in the UXDL behavior graph.

Surface Types & Host Parents

UXDL classifies screen surfaces using the optional 'type' attribute:

• page — Full view or primary route surface (e.g. billing).
• modal — Overlay dialog obscuring host screen. Requires 'parent' field.
• sheet — Bottom or side drawer surface. Requires 'parent' field.
• drawer — Slide-out side panel.
• overlay — Popover or dropdown menu overlay.
• panel — Embedded sub-surface or tab container.

Address Syntax & Examples

Screen addresses use clean, lowercase snake_case identifiers:

1Address format:
2screen_id
3
4Real-world domain address examples:
5- sign_in
6- billing
7- cancellation_review
8- checkout_modal

Canvas vs Document View

In Canvas view, a Screen renders as a prominent graph card containing its nested states and action ports. In Document view, it renders as a structured section outlining metadata, states, and interactive triggers.

Complete Valid Example

Here is a complete screen definition including surface type, host parent reference, states, and actions:

1screens:
2  cancellation_review:
3    name: Confirm Cancellation Modal
4    type: modal
5    parent: billing
6    metadata:
7      figma_url: "https://figma.com/file/abc123?node-id=402-12"
8    states:
9      default: Retention discount offer presented
10      processing: Cancellation request submitted to payment gateway
11    actions:
12      confirm_cancel:
13        name: Finalize Cancellation
14        relations:
15          cancelled:
16            to: billing
17            state: cancelled
18      accept_retention:
19        name: Accept 20% Offer
20        relations:
21          stay_active:
22            to: billing
23            state: active

What a Screen Does NOT Mean

A Screen is NOT a React/Next.js page component, NOT a URL path, and NOT a visual layout frame. It describes an addressable behavioral surface regardless of frontend component architecture.

Connected Primitives & Best Practices

• States — Screens contain nested variant states describing surface conditions.
• Actions — Screens contain interactive triggers available to actors.
• Naming rule — Always use unique snake_case strings (^[a-z0-9][a-z0-9_]*$). Never use spaces or uppercase letters.