UX Spec Pack Lite

Turns a designer's coded prototype into a validated engineering handoff package: capability scope, states, actions, screenshots, data-availability notes, and a final reference snapshot of relevant source, local design tokens, and visual assets. Lite replaces the static Figma-file handoff and gives engineers far more context than that file ever carried. What it does not do is move accountability: implementation choices, production data, and delivery stay with the engineering team, exactly as they do today. The pack informs that work — it never transfers it to designers.

A prototype is the working UI the designer built. A capability is one ticketed slice of behavior (a filter panel, a search box, or a whole page). The pack is the folder of files this toolkit produces for that handoff.

Designer quickstart

You do not write code, edit configuration, or run commands. Your agent handles those parts. You make the design decisions and review the result.

Once UX Spec Pack Lite is installed in the prototype project, give your agent this request:

Set up UX Spec Pack Lite for this prototype and guide me through the handoff. Ask me only for design or handoff decisions. Handle the files, configuration, checks, and commands yourself. Tell me when the review page is ready.

That is the whole starting procedure. If you return later, ask: “What’s next for the handoff?”

Your three touchpoints

1. One setup conversation. Your agent proposes a short handoff name and asks, in one batch:

   • which recognizable parts of the experience belong in this pack — choose one or several from the agent's suggested list, or name something it missed in your own words; an outside destination appears only when needed to show where an included journey ends;
   • which work item or ticket this belongs to;
   • whether you want a visual review board, and the Figma Design file when you do;
   • the deployed prototype's home link, if it exists yet.
   • where the finished pack will live: here with the prototype, or in a separate handoff or engineering project.

   Answer in plain language. “Specimen lookup and detail” is enough; you do not need to name code files, screens, repositories, or commits, or list what stays out. The first version is automatically 1.0.0. Your agent records the answers; you do not edit a header block.

2. One visual review. Your agent checks the prototype, writes the capability contracts, and runs the scripted capture. The run first proves that one real state opens correctly, so a bad address or prototype setup stops early instead of producing a folder full of useless screenshots. When it is clean, your agent tells you exactly where to look: open ux-spec-pack/handoff-overview.md and find Review the pictures and behavior. It contains every screenshot and plain-language behavior in one place. Tell the agent what is wrong, or say matches.

3. One journey-question batch. After your visual review, the agent asks about missing, loading, failure, empty, and other journey cases it could not learn from the prototype. “I don't know” is a valid answer; the handoff routes it to the right owner. The agent then completes the final checks and, if you asked for a board, publishes it into your Figma file.

The human pause between touchpoints 2 and 3 is deliberate: the tool never treats a successful script as design approval. Approval itself stays in your team's work tracker.

What the agent handles

• Technical setup: contract locations, element identifiers, screen size, browser choice, and how each pictured state opens directly from its board link—including seeded temporary messages and scroll position when needed.
• Contract writing, validation, screenshots, the engineering data notes, and the generated machine index.
• Plain-language recovery when something is missing or the prototype does not match its contract.
• Board planning, verification, duplicate-version protection, and temporary files. Temporary publishing files stay in the tool's cache rather than cluttering the project.

ux-spec-pack/handoff-overview.md is the front door in a new project. Its Status section says where the handoff is, its Review section is the designer checkpoint, and its final report says when the pack is ready. Existing projects that already use the legacy spec-pack/ folder keep using it; the update command never renames the folder.

Installation and updates

The prototype's maintainer or agent installs UX Spec Pack Lite from npm and initializes the project; the designer starts with the request above. When a newer version is available, the designer can say, “Update UX Spec Pack Lite and continue the handoff.” The agent installs the update, runs its safe project migration, and keeps project-specific settings and designer-authored content intact.

Setup uses Google Chrome or Microsoft Edge already on the computer. Only when neither exists does it download a screenshot browser. If that download is blocked by a corporate network, the tool explains what happened. If Node 20 or newer is missing, the agent should name that prerequisite plainly rather than asking the designer to troubleshoot package-manager output.

For engineers

Every completed handoff contains five core specification artifacts in the prototype repository's ux-spec-pack/ folder (or an existing legacy spec-pack/ folder):

After the final checks pass, the toolkit also creates README.md as the engineering entry point. It explains the pack and links to the files below; it does not add another specification artifact.

| File | What it answers | |---|---| | handoff-overview.md | intent, scope, accessibility, unknowns, plus the latest validation report | | contracts/<capability>.contract.md | states, actions, reachability, data IDs | | data-needs.md | each data: concept × six availability states, with owner-routed questions | | screenshots/ | one image per state × configured viewport | | ux-handoff.json | the machine index — start here for coding agents |

It also contains one script-owned supporting reference:

| Folder | What it provides | |---|---| | prototype-snapshot/ | final reference copy of the complete application source root plus verified local token and visual-asset folders |

When the designer requests a visual board, the completed handoff also contains a derived navigation flow under flows/ and, after successful publication, board.md with the published board identity.

Stable IDs (dashboard.main:ready, dashboard.main#filter-button, act:filter-panel/apply, data:dashboard-rows, …) join every file. Match by ID, never by label. A clean full capture inventories the included screens' rendered element IDs from the configured HTML attribute—normally data-spec-id—under screens[].elements in ux-handoff.json; designers never author or review them.

The prototype snapshot accompanies the deployed prototype link so engineering has both the rendered experience and its implementation context. It preserves the exact selected project-relative trees; it is not a runnable bundle. The final script excludes secrets, Git data, dependencies, generated build/coverage folders, and local font binaries. The corporate font stays installed at the application level and is visible in the running prototype. The agent discovers source, token, and asset roots from real project configuration and references—designers are never asked to choose filesystem paths. If a recorded folder moves, the core specification is still generated, but the handoff and board publication remain blocked until the agent finds the new location or, for optional token or asset material, the designer confirms that it no longer applies.

When a capability has intentional custom motion or another design rule that the contracts and overview cannot carry, the authoring pass may also create design-spec.md. It describes observable behavior in stack-neutral language and keeps framework-specific details only in evidence and source references. The generated README links it when present. It is optional and is not validated by UX Spec Pack Lite.

Install and initialize it from the prototype project's root:

npm install ux-spec-pack-lite
npx ux-spec-pack-lite init

For a later release, update the dependency and safely refresh the project-owned setup:

npm install ux-spec-pack-lite@latest
npx ux-spec-pack-lite update

Both init and update check the project's existing AGENTS.md and CLAUDE.md files and install or refresh a marker-bounded workflow block without changing surrounding project instructions. That managed block tells the coding agent to write capability contracts during implementation and to create, stamp, preserve, and reuse stable element IDs using the project's configured HTML attribute.

The project's lockfile records the exact installed toolkit version. Updates are explicit rather than automatic, so an existing handoff never changes unexpectedly. npx ux-spec-pack-lite validate re-checks the pack at any time.

Project-specific setup lives in spec-pack.config.json: test_id_attribute (how element IDs are stamped on the page), stack_profile (how a mock: ID becomes an address), contract_source_dir (where contract sources live beside the code), snapshot_paths (the verified source, token, and asset roots), viewports, work tracker, and board adapter. The core capture, index, and validation workflow does not assume React, MUI, or Jira. The current optional visual-board adapter targets Figma Design; that adapter choice remains explicit in configuration.

Same vocabulary as MVUX (capability, states table, actions table, honesty markers); Lite is the portable version for teams that do not share that repo.

What Lite does not promise

Git names the commit and the work tracker records approval. Screenshots are not proven to come from the named commit. They are the screenshots capture took when it ran, against the prototype it was pointed at. Honesty markers say what is [confirmed], [self-reported], and [unknown — owner]. Unknowns are marked, not blocked.

What Lite deliberately leaves out

These were in a heavier toolkit and were removed on purpose, so this one stays light enough for a designer to run and a mid-tier model to fill:

• A working-draft then final-handoff board lifecycle, board diffing, and republishing in place (each pack version is a new board page; old pages are history)
• Review ledgers, suggestion workflows, and approval files (approval lives in your work tracker)
• Provenance tags on every line, freeze evidence, and capture hashes
• A third model pass that hunts for gaps (the validator's report in the overview is the gap check)
• A standalone gaps.md, and a routine design-spec.md (the optional file is only for intentional custom motion or other rules the contract and overview cannot carry)

Working on the toolkit itself

This section is for people changing UX Spec Pack Lite, not using it.

Clone the repository, run npm install, and run npm run smoke — test/smoke.sh is the gate every script and skill change must pass (AGENTS.md has the working rules). The runtime allowlist in package.json ships scripts/, schemas/, templates/, and skills/; npm also includes package.json, this README, and the license. Development-only material — golden-sample/, docs/, reference/, and test/ — stays here.

Before a release, run npm run release:check and inspect npm pack --dry-run. The package's prepublishOnly safeguard runs the same complete smoke gate again if anyone invokes npm publish.

Inside this repository the installed command is not on the path, so the same commands are node scripts/cli.js <command> <pack-folder> … — for example node scripts/cli.js run golden-sample/ux-spec-pack --base-url http://localhost:4173 --yes with node golden-sample/prototype/server.js running. Script messages render the right form for their reader through scripts/lib/commands.js, so never hardcode either one.