UniversalSurfaceXD

Portable surface language, interchange JSON, and a browser UX lab for grid-based UIs. Active development line: v4 — see docs/roadmap-v4.md (what shipped before vs current vs future). The project pairs naturally with uDOS v3 (runnable Host + ThinUI) for canon validation; this repository stands alone: schemas, examples, Storybook, and the UX designer mockup do not require private infrastructure.

Development standards (UDN)

Shared with other github.com/fredporter/ repos:

• DEV.md — zones (.local/ / .compost/), implementation roots, commands
• TASKS.md — active Task Forge backlog
• DEV_CHECKLIST.md — pre/post dev pass
• AGENTS.md — agent / Cursor map
• docs/dev/WORKFLOW.md · docs/dev/TASK_FORGE.md

What you get

• Interchange — JSON schemas and examples under interchange/ (surface documents, UX bundles, validation scripts).
• Browser UX designer — SvelteKit app in browser-mockup/: catalog, composer, lab hub, optional Syncdown/Material theme preview (?sd=).
• Grid & graphics canon — Aligned with uDOS v3: 80×30 viewport, 16×24 px cells, teletext 2×3 bridge. See docs/decisions/UniversalSurfaceXD_v2-cannon.md and docs/udos-v3-style-bridge.md. Lab: /lab/grid-canon when the mockup is running.
• Storybook — Component workshop under src/stories/ (run npm run storybook).
• Design tokens & spine — spine/, staff/, export helpers.

Quick start

Requirements: Node.js 20+ (see .nvmrc).

git clone https://github.com/fredporter/UniversalSurfaceXD.git
cd UniversalSurfaceXD
npm install
npm run setup

UX designer (recommended first touch):

npm run ux-designer:dev

Open http://localhost:5173/lab — catalog, composer, grid canon, UX I/O.

Validate interchange examples:

npm run ux:validate-surfaces

Storybook:

npm run storybook

Optional: multi-repo workspace

If you also clone uDOS-v3 or other siblings, use a .code-workspace file (see docs/ux-designer-distribution.md). Missing folders are safe to omit; remove or adjust workspace entries for your layout.

Scope

In this repo

• UX vocabulary, surface document JSON, and validation.
• Browser mockup and Storybook prototypes.
• Figma / handoff notes and decision docs under docs/.
• Theme bridge experiments (e.g. Syncdown Material mapping) where included.

Out of scope

• Production app runtime for MDC, uDOS, or Syncdown (those live in their own repositories).
• Private or unreleased product binaries.

Project layout

uDOS integration (optional)

Runnable stack: github.com/fredporter/uDOS-v3. USXD usxd/0.1 surface JSON is validated there (packages/schemas/usxd-surface.schema.json). This repo’s surface-document schema targets the composer tree (meta + grid/stack roots).

Versioning and distribution

• Distribution is the Git repository (clone, tags, releases on GitHub). This is not published to the npm public registry.
• Root package.json sets "private": true so npm publish cannot accidentally publish the monorepo; the name field is for tooling and local linking only.
• Release line: 4.4.x. 4.4.0 shipped the public OSS baseline; 4.4.1 opens the v4 working line (see docs/roadmap-v4.md). Increase the patch for each milestone or doc/fix batch; reserve minor/major bumps for deliberate schema or product shifts. See CHANGELOG.md.

Contributing

See CONTRIBUTING.md. Pull requests welcome; keep interchange examples passing npm run ux:validate-surfaces and the browser-mockup npm run build.

Maintainer

Repository: github.com/fredporter/UniversalSurfaceXD.