uxd

uxd embeds a small UX design workspace into any repository. It gives agents a consistent place to inspect the repo, write UX specs, and preview interactive React mocks.

npx @basemachina/uxd init
npx @basemachina/uxd index
npx @basemachina/uxd add review-flow --version v1
npx @basemachina/uxd dev

What It Creates

npx @basemachina/uxd init creates:

• .uxd/app - Next.js preview app
• .uxd/content/specs - UX specs and mocks
• .uxd/index - generated repo/component summaries for agents
• .uxd/host.tsx / .uxd/host.css - optional providers and global CSS for previews
• .uxd/skills - Codex/Claude skill templates
• .github/workflows/uxd-preview-*.yml - optional PR previews on Cloudflare Workers

The CLI itself does not call an LLM. Codex or Claude reads .uxd/index and the installed uxd skill, then writes spec.md and mock*.tsx files. The CLI handles setup, repo indexing, mock registry generation, validation, and local preview startup.

Commands

npx @basemachina/uxd
npx @basemachina/uxd init [--agents codex,claude] [--deploy cloudflare-pr|none]
npx @basemachina/uxd index
npx @basemachina/uxd add <slug> [--version v1]
npx @basemachina/uxd component add <kebab-name> [--description "..."]
npx @basemachina/uxd component import <kebab-name> --from <path> --export <name|default>
npx @basemachina/uxd registry
npx @basemachina/uxd validate
npx @basemachina/uxd dev [--port 3000]
npx @basemachina/uxd sync
npx @basemachina/uxd update [--check]
npx @basemachina/uxd skill install <codex|claude> [--scope project|global]

uxd sync refreshes .uxd/app/ and .uxd/skills/ from the current uxd version's templates. User-authored specs (.uxd/content/specs/), custom components/import manifests (.uxd/components/), host files (.uxd/host.*), and .uxd/app/node_modules/ are preserved.

uxd update checks npm for a newer release. With a global install (npm install -g @basemachina/uxd) it runs npm install -g @basemachina/uxd@latest; with npx or a linked checkout it prints the right command for that setup.

Spec Layout

Versioned specs are the default:

.uxd/content/specs/{slug}/v1/spec.md
.uxd/content/specs/{slug}/v1/mock.json    # default
.uxd/content/specs/{slug}/v1/mock.tsx     # escape hatch

spec.md frontmatter can register one or more mocks:

mocks:
  - id: main
    title: Main flow
    file: mock
    frame: browser
    height: 560

Run npx @basemachina/uxd registry after adding mocks so the preview app can load them.

Real Project Components

By default, uxd mocks stay independent and use the JSON renderer. When fidelity depends on rendering a real project component, expose it through an opt-in adapter:

npx @basemachina/uxd index
npx @basemachina/uxd component import project-button --from src/components/Button.tsx --export Button

This writes .uxd/components/project-button.tsx, records metadata in .uxd/components/manifest.json, and makes the type available to JSON mocks:

{ "type": "project-button", "props": { "label": "Continue" }, "onClick": "next" }

Use .uxd/host.tsx for providers and .uxd/host.css for target global CSS or preview-only overrides needed by imported components.

Legacy Templates

For Rails-style views (.erb, .html.erb, .slim, .haml), uxd does not run the server runtime or convert templates automatically. Treat those files as design references, then create a React custom component that mimics their structure, class names, labels, and dynamic values:

npx @basemachina/uxd component add legacy-review-card \
  --description "Mimics app/views/reviews/_legacy_review_card.html.erb"
npx @basemachina/uxd registry

The component lives in .uxd/components/legacy-review-card.tsx and can be used from JSON mocks like any other custom type:

{ "type": "legacy-review-card", "props": { "title": "Refund review" } }

Add both the source template and the mimic component to componentHints so agents keep reading the legacy UI when revising the spec.

Dogfooding (examples/)

examples/ is a self-contained uxd workspace that mirrors templates/preview-app/ and hosts the renderer sandbox plus anonymized sample specs. It runs on every main push and is hosted as uxd-examples on Cloudflare Workers.

cd examples
npm run bootstrap   # sync templates/preview-app/ → .uxd/app/, install, regenerate registry
npm run dev         # local preview at http://localhost:3000

When you add a new primitive or composite to templates/preview-app/lib/json-renderer/, add a matching mock-<feature>.json under examples/.uxd/content/specs/sandbox/v1/ to verify it.

examples/app/views/ also includes Rails-style ERB/Slim partials, with examples/.uxd/components/legacy-review-card.tsx showing the recommended "mimic as custom component" path.

Cloudflare deploy needs two repo secrets: CLOUDFLARE_API_TOKEN (Edit Workers + Account Read) and CLOUDFLARE_ACCOUNT_ID. Each PR also gets its own preview worker (uxd-examples-pr-<N>) with the URL posted as a PR comment; the worker is deleted automatically on PR close. See examples/README.md for details and rollback steps.

Two Claude Code skills under .claude/skills/ (uxd-examples-dev, uxd-examples-add) wrap the common workflows.

Publishing

The package is scoped and public. Releases are managed with Changesets:

npm run changeset

Release flow

1. Create feature PRs against develop.

2. For every non-release PR, add a changeset:

   npm run changeset

   Choose patch, minor, or major, then write the user-facing release note.

3. If a PR should not publish a new package version, add an empty changeset:

   npm run changeset -- --empty

4. Merge approved feature PRs into develop.

5. Open the Prepare release button above, choose Run workflow, and leave source_branch as develop unless you are preparing from a temporary branch. The workflow reads pending changesets, updates versions and changelogs, and opens or updates the Version Packages PR into main.

6. Review and merge the Version Packages PR into main. The publish npm package workflow publishes the new npm version, updates the npm latest dist-tag, pushes the matching vX.Y.Z Git tag, and creates the GitHub Release.

The changeset check workflow fails PRs to develop that change the package without a changeset. main should only receive Version Packages release PRs. The repository secret NPM_TOKEN must have publish access to the @basemachina npm scope.