Stable Addresses

Definition & Purpose

Stable Addresses are the core mechanism that makes UXDL machine-verifiable. By giving every screen node, state variant, interactive trigger, transition outcome, and requirement slice a deterministic dot-separated address, teams ensure that PRDs, designs, code, and automated tests refer to the exact same product element.

Complete Address Hierarchy

UXDL 0.1 establishes a strict dot-separated address hierarchy:

1# Screen Address:
2screen_id
3
4# State Address:
5screen_id.states.state_id
6
7# Action Address:
8screen_id.actions.action_id
9
10# Relation Address:
11screen_id.actions.action_id.relations.relation_id
12
13# Slice Address:
14slices.slice_id

Domain Address Examples

Here is how a complete e-commerce billing flow translates into address notation:

• Screen: billing
• State: billing.states.past_due
• Action: billing.actions.retry_payment
• Relation: billing.actions.retry_payment.relations.success
• Slice: slices.payment_recovery

AI Agent & Tooling Usage

When coding agents (such as Claude, Cursor, Antigravity, or Gemini) analyze codebase changes or generate tests, they use stable addresses as exact reference targets. This eliminates guesswork and prevents agents from hallucinating non-existent screens or states.

Complete Mapping Example

Here is how YAML elements map directly to their stable address strings:

1screens:
2  billing:                                                  # Address: billing
3    states:
4      past_due: Payment past due                            # Address: billing.states.past_due
5    actions:
6      retry_payment:                                        # Address: billing.actions.retry_payment
7        relations:
8          success:                                          # Address: billing.actions.retry_payment.relations.success
9            to: billing
10            state: active