UI / UX Guide

This guide applies to host interfaces built around the NPM SDK. Treat viewer.ready() and the workflow-specific document requirements as prerequisites, and keep NPM calls out of PostMessage-only documentation. It describes host UI behavior; component API pages remain the source of truth for method and event contracts.

• Workflow guide index
• Viewer lifecycle
• Link each workflow section to its matching NPM component API reference.

Design the state model before arranging controls. Each visible control should have a known prerequisite, pending behavior, confirmed outcome, and recovery action.

• 1Identify the viewer and document state required by the workflow.
• 2Define host states and the documented result or event that advances each state.
• 3Render unavailable actions as disabled with an explanation when the prerequisite is not met.
• 4Send one user-initiated command, then show pending state until its documented completion condition.
• 5Update the confirmed UI only from the relevant result or event.
• 6Clean up subscriptions and transient UI state when the user exits the route.

Do not use a button click as proof that Canvas accepted a workflow. Read or subscribe to the documented state source for the capability, then render the host UI from that confirmed state. Where the SDK offers no read or completion contract, label the host state as requested or pending rather than applied.

• Viewer: distinguish mounting, ready, and unavailable states.
• Document workflows: distinguish no document, opening, active document, and open failure.
• Event-driven workflows: subscribe before enabling the action that can emit the event.
• Fire-and-forget workflows: do not show a completed state unless a separate documented event confirms it.

A workflow UI should make intermediate state visible and prevent conflicting actions. Keep host state scoped to the active document, active request, or captured annotation identifier so a late event cannot update the wrong screen.

• 1Unavailable: prerequisites are missing; show why the action cannot run.
• 2Ready: prerequisites are satisfied; allow the next user action.
• 3Pending: a command or user interaction is in progress; disable duplicate submission and keep Cancel available when the workflow supports it.
• 4Confirmed: the documented result or event has arrived; update the related host state.
• 5Failed or cancelled: discard only transient state for the failed workflow, preserve correctable inputs, and return to Ready when safe.

Validate host-owned inputs before a request, but do not invent SDK constraints. Surface documented SDK validation errors near the relevant field and retain valid input values so the operator can correct only the failed value.

• Use visible labels for form controls and provide text that explains disabled actions.
• Use aria-live for asynchronous status, errors, and completion messages that users must notice.
• Move focus into metadata dialogs when they open and return focus to the initiating control when they close.
• Keep keyboard access for every control and do not rely on color alone for status, priority, or selection.
• Prevent duplicate submissions while the same request is pending.

Place controls near the information they affect without obscuring the working drawing or model. A host panel is appropriate for record lists, metadata, and long-running workflow status; keep Canvas-native interaction visible while the user performs it.

• Keep the Viewer visible while operators select, draw, measure, compare, or inspect.
• Use a side panel for task lists, metadata, properties, and workflow status.
• Use a focused dialog for a bounded metadata or confirmation task, not for persistent navigation.
• Keep the primary action and its current status close together.
• On small screens, preserve a usable Viewer area and avoid hiding the only recovery action below the fold.

The host must distinguish a requested action from a confirmed outcome. A retry should use the current valid inputs and active document context; it must not reuse stale request IDs, selected identifiers, or results from a previous workflow.

• Keep a control pending until its documented promise result or event arrives.
• On failure, restore the last confirmed state and expose a specific retry or correction action.
• On cancellation, clear active tools and transient request state when the component API documents that action.
• Do not remove a host record after a fire-and-forget deletion request until its matching deleted event arrives.
• On route cleanup, unsubscribe listeners before destroying the viewer and clear transient local state.

Workflow documentation should be copyable, scoped to one integration mode, and honest about asynchronous behavior. Keep payload schemas in the component API reference and use the guide to explain decisions, ordering, and failure handling.

• Use one file per code block and name the real file path in its heading.
• Do not use tabbed code blocks in workflow pages.
• Show prerequisites, source setup, lifecycle cleanup, input validation, pending state, error handling, and a verification checklist.
• Use concrete NPM call shapes without ellipsis notation.
• Do not include PostMessage command names, payloads, or event envelopes in an NPM guide.
• Link to the exact NPM component page for detailed methods and payload fields.

Review each workflow in the supported NPM integration before publishing it.

• Controls are unavailable until their documented prerequisites are met.
• Each pending action has a visible status and cannot be submitted twice.
• Success is shown only after the documented result or event.
• Failure preserves correctable inputs and provides a usable next action.
• Keyboard focus, labels, status announcements, and contrast support the same workflow as pointer input.
• The Viewer stays visible during the primary task on desktop and small screens.
• Route changes remove listeners and do not leave stale pending state in the next workflow.
• Examples use verified NPM methods and link to the matching API reference.