START HEREAvailable

What is UXDL?

UXDL is a machine-readable behavioral contract for user-facing products. It gives Product, Design, Engineering, QA, and coding agents stable references for the same screens, states, actions, and relations.

Overview

UXDL (User Experience Description Language) formalizes expected user interface behavior into unambiguous, addressable declarations. It provides a shared target so product managers, designers, software engineers, and automated coding agents agree on exact product behavior before implementation starts.

The Interpretation Step

UXDL is specifically designed for the interpretation step between describing what a product should do (PRD, intent, user research) and deciding how to build it (technical architecture, DB schemas, component trees).

Rendering diagram...

UXDL occupies the behavioral contract layer between product intent and implementation.

Four Core Primitives

Every user interaction flow in UXDL is constructed using four simple primitives with stable snake_case identifiers:

Screen — A surface or modal a user interacts with (e.g. checkout). Address: checkout
State — A meaningful condition of a screen (e.g. payment_failed). Address: checkout.states.payment_failed
Action — An interactive trigger on a screen (e.g. retry_payment). Address: checkout.actions.retry_payment
Relation — The destination outcome following an action (e.g. to: billing). Address: checkout.actions.retry_payment.relations.success

Real-World Specification Preview

Here is a complete, minimal UXDL 0.1 document specifying an authentication and billing flow:

YAML

1uxdl: "0.1"
2app: Enterprise SaaS Platform
3title: Authentication & Subscription Management
4
5screens:
6  sign_in:
7    name: Sign In Surface
8    type: page
9    states:
10      default: Ready for credentials input
11      invalid_credentials: Email or password incorrect
12    actions:
13      submit:
14        name: Submit Credentials
15        relations:
16          success:
17            to: billing
18          failed:
19            to: sign_in
20            state: invalid_credentials
21
22  billing:
23    name: Billing Overview
24    type: page
25    states:
26      active: Plan up to date
27      past_due: Payment past due
28    actions:
29      retry_payment:
30        name: Retry Failed Payment
31        relations:
32          success:
33            to: billing
34            state: active

What UXDL Does Not Do

UXDL does not try to replace every product artifact. Keep research, strategy, detailed visual design, technical architecture, and project planning where they make the most sense. UXDL focuses strictly on making observable product behavior addressable and reviewable.