User Experience and Design

User experience and design requirements for clear, reliable VARIO Cloud app integrations.

A Public App must provide a clear, understandable, and reliable user experience that fits naturally into VARIO Cloud.

Users should be able to understand what the app is doing, what input is required, whether an operation was successful, and what they can do when something goes wrong.

VARIO Cloud Apps are external web applications that can be embedded into the VARIO Cloud user interface through defined UI integration points.

Technical implementation details for navigation, dialogs, iframe communication, sizing, and other integration mechanisms are documented in UI Integration.

This page defines the user experience criteria applied during App Store review.

Provide a complete user experience

Customer-facing parts of the app must appear complete and ready for productive use.

Users must not encounter:

• unfinished pages;
• placeholder content;
• internal development information;
• unexplained technical values;
• broken navigation;
• controls that do not perform an available action;
• empty pages without explanation;
• functionality that appears available but cannot be used.

If a feature is intentionally unavailable because configuration, permissions, or another prerequisite is missing, the app should explain this to the user.

Fit naturally into VARIO Cloud

Where an app is embedded into VARIO Cloud, its user interface should behave like part of a coherent business application.

The app does not need to reproduce the VARIO Cloud design exactly, but its interface should be compatible with the context in which it appears.

In particular:

• content must fit within the available integration area;
• important information and actions must remain usable without unnecessary horizontal scrolling;
• dialogs must work within the available dialog context;
• the app should not unnecessarily duplicate VARIO Cloud navigation;
• navigation between VARIO Cloud and the app should be predictable;
• the app must not interfere with surrounding VARIO Cloud functionality.

The app should use the integration mechanisms provided by VARIO Cloud instead of implementing workarounds around the embedded application context.

Use the intended UI integration points

UI elements must be placed at appropriate VARIO Cloud integration points.

The location of an app function should correspond to the context in which a user would reasonably expect to find it.

Examples include:

• a main navigation entry for a larger standalone app area;
• a contextual action where the app extends a specific VARIO business object;
• a dialog for a focused task, editor, or configuration flow.

The app must not insert unrelated functionality into an integration point simply because the technical integration point is available.

Available integration points and their implementation are documented in the App Manifest and UI Integration documentation.

Keep navigation understandable

Users must be able to understand where they are and how to continue.

Navigation should:

• use clear labels;
• lead to the expected destination;
• avoid unnecessary intermediate screens;
• provide an obvious way to leave a detail view or dialog where appropriate;
• preserve relevant context when moving between related processes.

The app must not create navigation loops or leave users on pages from which the intended workflow cannot be continued.

If a user follows a link to an external service, the transition should be understandable from the action being performed.

Use clear action labels

Buttons and other actions should describe what they do.

Prefer specific labels such as:

• Save configuration
• Connect account
• Import orders
• Create shipment
• Retry
• Cancel

Avoid vague labels such as:

• OK
• Go
• Execute
• Process

where the result of the action is not obvious from the surrounding context.

Destructive actions must be clearly distinguishable from ordinary actions.

Do not hide important consequences

Before executing an action with a significant or irreversible effect, the app must make the expected consequence clear.

This is particularly important for actions that:

• delete data;
• overwrite existing data;
• synchronize a large amount of data;
• create multiple business objects;
• change important configuration;
• disconnect an external service;
• trigger an external transaction.

Depending on the impact, the app should provide an appropriate confirmation or preview.

A generic confirmation such as “Are you sure?” is not sufficient for a high-impact action if the user cannot understand what will actually happen.

The confirmation should describe the relevant consequence, for example: “Disconnecting this account will stop automatic order imports.”

Validate input before processing

Forms must validate user input where invalid values can prevent the intended operation or create incorrect data.

Validation should occur as close as practical to the affected field or action.

Validation messages must explain:

• what is wrong;
• which value or field is affected;
• how the user can correct the problem.

The app should not wait for a technical backend error where the problem could reasonably have been identified before submitting the form.

Preserve user input where possible

A validation error or temporary technical failure should not unnecessarily discard information the user has already entered.

Where practical, the app should preserve valid input and allow the user to correct only the affected information.

Users should not have to repeat a large configuration or data-entry process because one field was invalid.

Show loading and processing states

When an operation is not completed immediately, the user must receive appropriate feedback.

Depending on the operation, this may include:

• a loading indicator;
• a disabled action while the request is processing;
• a progress state;
• a background processing status;
• a message explaining that processing will continue asynchronously.

The app must avoid creating the impression that nothing happened after the user started an operation.

Actions must also be protected against accidental repeated execution where multiple clicks could create duplicate operations.

Show successful completion

Where completion is not already obvious from the resulting screen, the app should confirm that an important operation succeeded.

For example:

• configuration saved;
• account connected;
• synchronization started;
• import completed;
• shipment created;
• operation retried successfully.

Success messages should describe the result rather than simply displaying a generic Success.

Provide useful empty states

An empty page or list must not appear broken.

Where no data is available, the app should explain why where this can reasonably be determined.

A useful empty state may tell the user:

• that no records exist yet;
• that a filter returned no results;
• that configuration is still required;
• that no synchronization has been performed yet;
• what action can be taken next.

For example:

No orders have been imported yet. Connect your shop account and start the first import.

is more useful than:

No data.

Provide understandable error messages

Customer-facing error messages must be understandable without requiring the user to interpret a stack trace, HTTP response, or internal identifier.

An error message should answer as many of the following questions as are relevant:

• What failed?
• What was affected?
• Was anything already processed?
• Can the user retry?
• Does configuration need to be corrected?
• Does the user need additional permissions?
• Should the App Provider be contacted?

For example:

The order could not be imported because the country code XX is not supported. Correct the address in the source system and retry the import.

is preferable to:

Request failed: 422.

Customer-facing error messages must not expose access tokens, passwords, API keys, secrets, internal stack traces, or other sensitive technical information.

Technical details may be stored separately for troubleshooting where appropriate.

Distinguish warnings from errors

The app should clearly distinguish between:

• information;
• warnings;
• errors;
• successful completion.

A warning should not look like a completed error if the user may continue safely.

An error should not be presented as a harmless informational message when the intended operation did not complete.

Make partial success visible

If an operation processes multiple records and only part of the operation succeeds, the user must not receive a generic success message for the complete operation.

The result should make clear, where relevant:

• how many records were processed;
• how many succeeded;
• how many failed;
• whether records remain unprocessed;
• how failed records can be inspected or retried.

For example:

Import completed: 96 orders imported, 4 orders require attention.

is preferable to:

Import completed.

when four records actually failed.

Make configuration understandable

App configuration should be understandable to the intended customer without requiring undocumented knowledge from the App Provider.

Configuration fields should:

• use meaningful labels;
• explain non-obvious values;
• identify required fields;
• provide reasonable defaults where possible;
• distinguish optional from mandatory settings.

If a setting can have a significant impact on customer data or automation, its effect should be explained before the user enables it.

Handle missing permissions clearly

If a user does not have the authorization required for a function, the app must handle this situation intentionally.

Depending on the context, the app may:

• hide functionality the user is not allowed to access;
• disable the action and explain why;
• display an appropriate authorization message.

The app must not present a broken page or generic technical error merely because the current user lacks an app-specific permission.

Technical authorization must still be enforced independently of the user interface, as described in Permissions and Data Quality.

Respect the user's language

Customer-facing text should be written consistently and professionally.

The app should avoid mixing languages unnecessarily within the same workflow.

VARIO Cloud can provide language context to embedded App integrations. Apps supporting multiple languages should use the provided language context where appropriate.

The available UI parameters are documented in UI Integration.

If the app is only available in specific languages, this must be stated in the App Store listing.

Use consistent terminology

The same business object or action should generally use the same term throughout the app.

Avoid changing terminology between:

• navigation;
• forms;
• status messages;
• error messages;
• documentation.

Where the app refers to standard VARIO concepts, using terminology that VARIO users already recognize is preferred unless a different term is required by the connected system.

External authentication and account connection

If the app requires the customer to connect an external account, the process must clearly distinguish between:

• VARIO Cloud;
• the App Provider;
• the external service.

Users must understand which system they are authenticating with and what the connection is being established for.

The app must not imitate a VARIO login screen to collect VARIO credentials.

Authentication requirements and external prerequisites must also be accurately described in the App Store listing.

Installation experience

If the user must complete configuration during or immediately after installation, the app should guide the user through the required steps in a logical order.

The installation experience should make clear:

1. what needs to be configured;
2. which external account or credentials may be required;
3. whether the connection was successful;
4. when the app is ready to use.

A customer should not have to search through unrelated areas of the app to determine why a newly installed app is not yet operational.

Uninstallation experience

Where the app provides an uninstallation or disconnection interface, the user should understand the consequence of the action.

Where relevant, explain whether uninstalling the app:

• stops synchronization;
• disconnects an external service;
• retains app data;
• leaves previously created VARIO business data unchanged.

The user must not be given the impression that historical VARIO business objects will be deleted unless that is actually part of the intended behavior.

Basic usability and accessibility

The app should follow common web usability and accessibility practices.

In particular:

• interactive controls should be clearly identifiable;
• form fields should have understandable labels;
• important information should not rely solely on color;
• keyboard interaction should work for ordinary form and navigation elements where reasonably applicable;
• text and controls should remain readable in the intended integration context.

VARIO may require improvements where a design makes essential app functionality unnecessarily difficult to use.

Avoid disruptive behavior

An app must not unnecessarily disrupt the VARIO Cloud user experience.

The app should avoid:

• unexpected redirects;
• automatically opening multiple windows or tabs;
• repeated pop-ups;
• unnecessary confirmation dialogs;
• automatically starting high-impact operations without an intentional user action;
• taking over navigation unrelated to the app's functionality.

User attention should be requested only where it is relevant to completing the intended task.

What VARIO reviews

During the user experience review, VARIO may verify in particular whether:

• the app appears complete and ready for customer use;
• the app fits appropriately into its VARIO Cloud integration context;
• navigation and actions are understandable;
• forms provide appropriate validation;
• important operations provide loading and completion feedback;
• empty states explain what the user can do next;
• errors are understandable and actionable;
• partial failures are visible;
• destructive or high-impact actions provide appropriate safeguards;
• missing permissions are handled intentionally;
• configuration and installation can be completed without undocumented knowledge;
• customer-facing terminology and language are consistent;
• the user understands when an external system or account is involved;
• essential functionality can be used without unnecessary friction.

VARIO may request usability improvements before approval where an app is technically functional but would provide an unclear or unreliable customer experience.