UXSpec Builder
Interactive workflow for creating UXSpec files — the JSON format that unifies state machines and visual specifications for AI agents. Each phase has a dedicated skill with detailed guidance.
Trigger
Use when the user wants to create, build, or scaffold a .uxspec.json file, or asks "help me write a uxspec".
Workflow
Follow these phases in order. Each phase produces a concrete artifact before moving on. Read the linked skill for detailed decision guidance.
Phase 1 — Gather Requirements
→ See gather/SKILL.md
Establish who, what, and why before writing JSON. Ask about structural requirements (states, events, context), design context (audience, brand personality, references), and UX intent (primary actions, copy tone, first-time experience). Summarize and confirm before proceeding.
Phase 2 — Design the State Machine
→ See states/SKILL.md
Build $machine — compound and leaf states, transitions, guards, entry/exit actions, invocations. Map happy paths first, then unhappy paths. Cover empty, loading, error, and success states. Simplify aggressively. Present as a text diagram.
Phase 3 — Define Tokens and Visuals
→ See tokens/SKILL.md and visuals/SKILL.md
Define $tokens (color, typography, spacing, timing, radius) and $elements (reusable templates). Add $visual to every leaf state with intentional layout, descriptive $description fields, testId on interactive elements, and aria labels.
Read references/format-reference.md for token syntax, element types, and visual structure.
Phase 4 — Add Runtime Semantics
→ See wire/SKILL.md and animate/SKILL.md
Define $context, $events, $actions, $effects. Wire binding, visibleWhen, enabledWhen, onPress, onChange. Add $animations and onEnter choreography where state transitions need smoothing.
Read references/runtime-semantics.md for expression syntax and action/effect kinds.
Also apply:
clarify/SKILL.md — review all copy and descriptionsharden/SKILL.md — add edge case handling and resilience
Phase 5 — Generate and Verify
→ See review/SKILL.md
- Write the spec to
examples/<name>.uxspec.json
- Validate:
bun run src/compiler/cli.ts validate examples/<name>.uxspec.json
- If validation fails, fix reported issues (the compiler returns structured issue codes)
- Compile:
bun run src/compiler/cli.ts compile examples/<name>.uxspec.json
- Inspect:
bun run src/compiler/cli.ts inspect examples/<name>.uxspec.json
- Run the full quality review from
review/SKILL.md
- Apply
extract/SKILL.md to consolidate repeated patterns
- Report: states, assertions, initial resolution, unresolved refs/tokens, compiled output path
Issue Resolution
| Code |
Fix |
UNDECLARED_CONTEXT_VAR |
Add missing field to $context |
UNDECLARED_EVENT |
Add missing event to $events |
UNDECLARED_TARGET |
Fix transition target to match a valid state path |
UNSUPPORTED_EXPR_OP |
Replace with a supported operator (see spec) |
INVALID_ASSIGN_PATH |
Ensure path starts with context. |
UNKNOWN_TOKEN_REFERENCE |
Add missing token to $tokens or fix the path |
UNKNOWN_ELEMENT_REFERENCE |
Add missing element to $elements or fix the name |
INVALID_MACHINE_INITIAL |
Set $machine.initial to a valid top-level state |
INVALID_COMPOUND_INITIAL |
Set compound state initial to a valid child name |
Skills
| Skill |
Phase |
Purpose |
gather |
1 |
Design context, requirements, UX intent |
states |
2 |
State machine design and simplification |
tokens |
3 |
Color, typography, spacing, timing tokens |
visuals |
3 |
$visual blocks, layout, descriptions, elements |
wire |
4 |
Context, events, actions, effects, bindings |
animate |
4 |
$animations, onEnter, motion timing |
clarify |
3–4 |
Copy, descriptions, error/empty/loading text |
harden |
4 |
Edge cases, resilience, accessibility |
extract |
5 |
Consolidate reusable elements and tokens |
review |
5 |
Quality audit before shipping |
Key Rules
- File extension:
.uxspec.json
- Schema:
https://raw.githubusercontent.com/johnlindquist/uxspec/main/schema/uxspec.schema.json
- Required top-level:
$schema, $description, $machine
$machine requires: id, initial, states- Leaf elements (
text, button, input, icon, shape, badge, bar) MUST NOT have children
- Container elements (
group, layer, grid, stack-h, stack-v) MAY have children
- Token references:
"{path.to.token}" — curly braces inside a string
- Element references:
{ "$ref": "name", ...params }
- Expressions: S-expression arrays like
["==", ["var", "context.x"], true]
- All
$-prefixed properties are reserved
Reference Files
references/format-reference.md — Token syntax, element types, visual structure, layout primitivesreferences/runtime-semantics.md — Context, events, actions, effects, expressions, transitionsreferences/minimal-example.md — Complete minimal spec you can use as a starting template
1---2name: uxspec3description: Walk through building a UXSpec (.uxspec.json) file — gathering requirements, making design decisions about layout/typography/color/motion/accessibility, designing the state machine, defining visuals, then compiling and verifying the output.4---56# UXSpec Builder78Interactive workflow for creating UXSpec files — the JSON format that unifies state machines and visual specifications for AI agents. Each phase has a dedicated skill with detailed guidance.910## Trigger1112Use when the user wants to create, build, or scaffold a `.uxspec.json` file, or asks "help me write a uxspec".1314## Workflow1516Follow these phases in order. Each phase produces a concrete artifact before moving on. Read the linked skill for detailed decision guidance.1718### Phase 1 — Gather Requirements19→ See `gather/SKILL.md`2021Establish who, what, and why before writing JSON. Ask about structural requirements (states, events, context), design context (audience, brand personality, references), and UX intent (primary actions, copy tone, first-time experience). Summarize and confirm before proceeding.2223### Phase 2 — Design the State Machine24→ See `states/SKILL.md`2526Build `$machine` — compound and leaf states, transitions, guards, entry/exit actions, invocations. Map happy paths first, then unhappy paths. Cover empty, loading, error, and success states. Simplify aggressively. Present as a text diagram.2728### Phase 3 — Define Tokens and Visuals29→ See `tokens/SKILL.md` and `visuals/SKILL.md`3031Define `$tokens` (color, typography, spacing, timing, radius) and `$elements` (reusable templates). Add `$visual` to every leaf state with intentional layout, descriptive `$description` fields, `testId` on interactive elements, and `aria` labels.3233Read `references/format-reference.md` for token syntax, element types, and visual structure.3435### Phase 4 — Add Runtime Semantics36→ See `wire/SKILL.md` and `animate/SKILL.md`3738Define `$context`, `$events`, `$actions`, `$effects`. Wire `binding`, `visibleWhen`, `enabledWhen`, `onPress`, `onChange`. Add `$animations` and `onEnter` choreography where state transitions need smoothing.3940Read `references/runtime-semantics.md` for expression syntax and action/effect kinds.4142**Also apply:**43- `clarify/SKILL.md` — review all copy and descriptions44- `harden/SKILL.md` — add edge case handling and resilience4546### Phase 5 — Generate and Verify47→ See `review/SKILL.md`48491. Write the spec to `examples/<name>.uxspec.json`502. Validate: `bun run src/compiler/cli.ts validate examples/<name>.uxspec.json`513. If validation fails, fix reported issues (the compiler returns structured issue codes)524. Compile: `bun run src/compiler/cli.ts compile examples/<name>.uxspec.json`535. Inspect: `bun run src/compiler/cli.ts inspect examples/<name>.uxspec.json`546. Run the full quality review from `review/SKILL.md`557. Apply `extract/SKILL.md` to consolidate repeated patterns568. Report: states, assertions, initial resolution, unresolved refs/tokens, compiled output path5758### Issue Resolution5960| Code | Fix |61|------|-----|62| `UNDECLARED_CONTEXT_VAR` | Add missing field to `$context` |63| `UNDECLARED_EVENT` | Add missing event to `$events` |64| `UNDECLARED_TARGET` | Fix transition target to match a valid state path |65| `UNSUPPORTED_EXPR_OP` | Replace with a supported operator (see spec) |66| `INVALID_ASSIGN_PATH` | Ensure path starts with `context.` |67| `UNKNOWN_TOKEN_REFERENCE` | Add missing token to `$tokens` or fix the path |68| `UNKNOWN_ELEMENT_REFERENCE` | Add missing element to `$elements` or fix the name |69| `INVALID_MACHINE_INITIAL` | Set `$machine.initial` to a valid top-level state |70| `INVALID_COMPOUND_INITIAL` | Set compound state `initial` to a valid child name |7172## Skills7374| Skill | Phase | Purpose |75|-------|-------|---------|76| `gather` | 1 | Design context, requirements, UX intent |77| `states` | 2 | State machine design and simplification |78| `tokens` | 3 | Color, typography, spacing, timing tokens |79| `visuals` | 3 | $visual blocks, layout, descriptions, elements |80| `wire` | 4 | Context, events, actions, effects, bindings |81| `animate` | 4 | $animations, onEnter, motion timing |82| `clarify` | 3–4 | Copy, descriptions, error/empty/loading text |83| `harden` | 4 | Edge cases, resilience, accessibility |84| `extract` | 5 | Consolidate reusable elements and tokens |85| `review` | 5 | Quality audit before shipping |8687## Key Rules8889- File extension: `.uxspec.json`90- Schema: `https://raw.githubusercontent.com/johnlindquist/uxspec/main/schema/uxspec.schema.json`91- Required top-level: `$schema`, `$description`, `$machine`92- `$machine` requires: `id`, `initial`, `states`93- Leaf elements (`text`, `button`, `input`, `icon`, `shape`, `badge`, `bar`) MUST NOT have `children`94- Container elements (`group`, `layer`, `grid`, `stack-h`, `stack-v`) MAY have `children`95- Token references: `"{path.to.token}"` — curly braces inside a string96- Element references: `{ "$ref": "name", ...params }`97- Expressions: S-expression arrays like `["==", ["var", "context.x"], true]`98- All `$`-prefixed properties are reserved99100## Reference Files101102- `references/format-reference.md` — Token syntax, element types, visual structure, layout primitives103- `references/runtime-semantics.md` — Context, events, actions, effects, expressions, transitions104- `references/minimal-example.md` — Complete minimal spec you can use as a starting template
johnlindquist