Plugin UI Best Practices

This guide captures the UI patterns already visible in NashTwin's existing plugin surfaces. It is based on the current Marketplace cards, the Devicer setup flow, and the Nash Optimization simulation panel rather than on generic plugin-marketplace advice.

Use this alongside the Plugin SDK and Plugin Contract when your plugin exposes UI through the host product.

Design for the Host Product, Not a Microsite

Plugin UI in NashTwin is embedded inside an existing CRM and operations workflow. That means your surface should feel like a focused extension of the page the user is already on.

Good plugin UI in this repo does the following:

• keeps the primary task obvious within one screen
• fits inside cards, panels, and collapsible sections
• uses compact summaries before detailed inspection
• explains guardrails, status, and consequences without sending the user elsewhere

Avoid turning a plugin panel into a detached mini-application with unrelated navigation, heavy branding, or full-screen control density that fights the host shell.

Pattern 1: Marketplace Cards

The Marketplace card is the first UI contract many users see. Existing cards in NashTwin keep the structure tight and predictable.

Include these elements:

• plugin icon or clear fallback initials
• plugin name and concise description
• one status pill such as ACTIVE or INACTIVE
• lightweight metadata such as author, version, capabilities, and event coverage
• one primary action, for example install, enable, or disable

Best practices

• Keep descriptions short enough to scan in place.
• Put the install state next to the name, not buried in the footer.
• Reserve the strongest button style for the primary action.
• Show capability and event scope in plain language so admins can decide quickly.
• If access is blocked by plan or policy, show that in the card area itself instead of failing later.

Pattern 2: Step-Based Setup Panels

The Devicer setup flow is a good model for operational plugins that require installation, snippets, origin registration, or configuration handoff.

Use a numbered setup sequence when the user must complete work in order.

Best practices

• Break setup into 2 to 5 explicit steps.
• Keep each step action-oriented, for example "Add the snippet" or "Register your website origin".
• Put copyable code or tokens directly beside the step that uses them.
• Label public values honestly. If something is a publishable key, say that it is not a secret.
• Show warnings early when the plugin is disabled, unconfigured, or operating in a permissive fallback mode.
• Keep configuration edits local to the panel whenever possible.

Good examples from current UI

• snippet copy affordance beside the generated script tag
• explicit warning when no origins are configured
• origin limit message tied to plan level
• disabled-state banner when the plugin is installed but inactive

Pattern 3: Decision and Analysis Panels

The Nash Optimization panel shows how to structure a higher-density plugin UI without becoming unreadable.

It separates the workflow into three layers:

1. control inputs
2. ranked result output
3. follow-up governance and feedback capture

Best practices

• Keep the control form and result view visually separate.
• Limit first-view output to the top few results. The current pattern is three to five moves.
• Pair every recommendation with supporting evidence, not just a score.
• Show uncertainty or confidence explicitly.
• Make policy state visible near the result, not only in a settings area.
• Keep feedback loops in the same panel when the plugin depends on outcome capture, review, or approval.

What to surface with every recommendation

• title
• short summary
• rank
• expected utility or equivalent scoring metric
• confidence or trust signal
• risk summary
• supporting evidence
• reasoning notes or policy notes

Status, Error, and Empty States

Current NashTwin plugin UI does not hide operational reality. It surfaces state directly in the panel.

Always handle:

• disabled plugin state
• pending async work
• permission or plan gating
• quota exhaustion or policy blocks
• no data yet
• action failure with human-readable error text
• successful completion when the user needs confirmation

Best practices

• Use clear banners for warnings, errors, and success messages.
• Keep empty states specific, for example "No simulation output yet" rather than "No data".
• When an action is blocked by policy, explain the exact reason.
• Do not rely on color alone to express state. Add text labels.

Make the Primary Workflow Fast

Plugin UI should not slow down the main CRM task.

Examples already present in the repo point to the right bar:

• Marketplace actions are one click from the card.
• Devicer setup gives copy-ready artifacts immediately.
• Optimization keeps launch controls, results, and feedback in one continuous surface.

Best practices

• Minimize navigation hops.
• Do not require users to remember IDs that the product can prefill or derive.
• Prefer inline feedback over redirect-driven workflows.
• Keep submission and save flows short enough that the user can stay in context.
• If your plugin augments a form submission, do not make the main transaction depend on non-critical enrichment when a graceful fallback is possible.

Write for Operators, Not Just Developers

Most plugin UI in NashTwin is used by admins, operators, or reviewers rather than the engineer who authored the integration.

That means labels should describe the business action, not just the implementation detail.

Prefer:

• "Run simulation"
• "Record outcome"
• "Allowed origins"
• "Approval required"

Avoid leading with internal jargon when a plain-language label would work better.

Respect Density and Mobile Layouts

The current plugin surfaces use dense desktop layouts but still collapse cleanly to stacked mobile flows.

Best practices

• Build forms and cards that can wrap without losing hierarchy.
• Assume long plugin descriptions, IDs, and URLs need truncation or wrapping.
• Avoid side-by-side controls that become unusable on narrow screens.
• Keep badges, pills, and metadata compact.
• Use sticky or side navigation sparingly and only for long-form documentation, not for transactional plugin panels.

Accessibility and Interaction Quality

At minimum, your UI surface should:

• use semantic buttons and form controls
• label every input clearly
• keep keyboard navigation intact
• expose status text in addition to color
• avoid hover-only affordances for critical actions
• preserve readable contrast in both light and dark contexts when applicable

Security and Trust Signals

Plugins often surface keys, origins, or operational controls. The UI should help the user understand what is safe to copy and what is sensitive.

Best practices

• Clearly separate publishable values from secrets.
• Explain what an allow-list or policy switch actually does.
• Show review and approval status near risky actions.
• When a plugin writes derived data or operates under policy controls, surface that governance context in the panel.

Checklist

Before shipping a plugin UI, confirm that it:

• matches the host product shell instead of competing with it
• has one obvious primary action per major state
• handles disabled, empty, pending, error, and success states
• explains operational consequences in the panel itself
• keeps setup steps in a short, ordered flow when sequence matters
• shows evidence and confidence for ranked or scored results
• supports narrow screens without breaking the workflow
• avoids blocking the core CRM task when the plugin can degrade gracefully

Summary

The existing NashTwin plugin surfaces favor compact cards, explicit setup steps, and task-focused decision panels. Follow those patterns. The best plugin UI in this product helps the operator act quickly, understand policy and state, and stay inside the surrounding workflow rather than escaping into a disconnected custom app.