uxspec

Category: Content & Multimedia | Uploader: johnlindquist | Downloads: 0 | Version: v1.0（Latest）

Walk through building a UXSpec (.uxspec.json) file — gathering requirements, designing the state machine, defining visuals, then compiling and verifying the output.

Changelog: Source: GitHub https://github.com/johnlindquist/uxspec

Directory Structure

Current level: skills/

📁 references/
- 📄 format-reference.md 3.4 KB
- 📄 minimal-example.md 4.3 KB
- 📄 runtime-semantics.md 4.0 KB
📄 SKILL.md 4.8 KB

SKILL.md

---
name: uxspec
description: Walk through building a UXSpec (.uxspec.json) file — gathering requirements, designing the state machine, defining visuals, then compiling and verifying the output.
---

# UXSpec Builder

Interactive workflow for creating UXSpec files — the JSON format that unifies state machines and visual specifications for AI agents.

## 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.

### Phase 1 — Gather Requirements

Ask the user:
1. **What is this component/page?** (e.g., "login form", "toast notifications", "media player")
2. **What are the key states?** (e.g., "idle, loading, error, success")
3. **What events drive transitions?** (e.g., "SUBMIT, INPUT_CHANGED, HTTP_OK, HTTP_ERROR")
4. **What context data is needed?** (e.g., "email: string, password: string, error: string | null")
5. **Any reusable elements?** (e.g., "input field with label, action button")

Summarize back to the user as a bullet list before proceeding.

### Phase 2 — Design the State Machine

Build the `$machine` section:
- Define compound states (parents) and leaf states (children)
- Every compound state needs an `initial` child
- Map events to transitions with optional guards and actions
- Add `entry`/`exit` actions where needed (e.g., set loading flag, clear errors)
- Add `invoke` for long-running effects (HTTP calls, timers)

Present the state graph as a text diagram:

```
idle --SUBMIT--> loading
loading --HTTP_OK--> success
loading --HTTP_ERROR--> error
error --RETRY--> loading
```

### Phase 3 — Define Tokens and Visuals

1. Define `$tokens` — colors, spacing, radius, font, timing (follow W3C Design Tokens format)
2. Define `$elements` — reusable element templates with `params`
3. Add `$visual` to each leaf state — container layout, slots with elements
4. Add `testId` to interactive elements for assertions
5. Add `aria` labels for accessibility

Read `references/format-reference.md` for token syntax, element types, and visual structure.

### Phase 4 — Add Runtime Semantics

1. Define `$context` — typed fields with defaults
2. Define `$events` — with source and payload types
3. Define `$actions` — assign, emit, log
4. Define `$effects` — http, timer, navigate, focus
5. Wire `binding`, `visibleWhen`, `enabledWhen`, `onPress`, `onChange` on elements

Read `references/runtime-semantics.md` for expression syntax and action/effect kinds.

### Phase 5 — Generate and Verify

1. Write the spec to `examples/<name>.uxspec.json`
2. Validate: `bun run src/compiler/cli.ts validate examples/<name>.uxspec.json`
3. If validation fails, fix reported issues (the compiler returns structured issue codes)
4. Compile: `bun run src/compiler/cli.ts compile examples/<name>.uxspec.json`
5. Inspect: `bun run src/compiler/cli.ts inspect examples/<name>.uxspec.json`
6. Report to the user:
   - Number of states and assertions
   - Whether initial resolves to a leaf state
   - Any unresolved refs or token aliases
   - The compiled output path

### Issue Resolution

If the compiler reports issues, map codes to fixes:

| 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 |

## Key Rules

- File extension: `.uxspec.json`
- Schema: `https://uxspec.dev/0.2/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 primitives
- `references/runtime-semantics.md` — Context, events, actions, effects, expressions, transitions
- `references/minimal-example.md` — Complete minimal spec you can use as a starting template

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

uxspec

Directory Structure

SKILL.md

Report

Notice