Create a UXDL Project

Project Structure Strategy

Most projects should begin with the simplest structure that works. A single UXDL YAML file is fully valid and natively parsed by the editor. As application scope grows across multiple domain teams, split features into explicit feature modules declared inside uxdl.project.yaml.

Single-File Projects

A single .uxdl.yaml file contains all actors, screens, states, actions, relations, and slices in one document. It is ideal for feature specs, single user flows, and lightweight prototypes.

Multi-File Projects Profile

For large enterprise SaaS platforms, create a root uxdl.project.yaml manifest pointing to module files:

1uxdl: "0.1"
2project:
3  id: saas_platform
4  name: Enterprise SaaS Engine
5modules:
6  - id: auth
7    path: flows/auth.uxdl.yaml
8  - id: billing
9    path: flows/billing.uxdl.yaml
10  - id: dashboard
11    path: flows/dashboard.uxdl.yaml

Module Ownership & Address Resolution

UXDL enforces strict single-module ownership to prevent address collision:

• One Owner Rule — Every screen ID, actor ID, or slice ID MUST be defined in exactly one module. Duplicate ownership across modules is a structural error.
• Global Reference Resolution — Relations keep short screen IDs across modules. Moving an element to a different module file does not change its global UXDL address.
• Portable Export — The UXDL editor composes a single-file composed.uxdl.yaml artifact for tools or AI agents that consume single documents.