Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

User Interface Guidelines

User Interface Guidelines

These guidelines are loosely based on the Eclipse UI guidelines. Topics are organized in alphabetical order.

Also make sure to check out the Accessibility Guidelines for the Commerce Manager.


  • Rather than defining key bindings using Windows-specific command keys (Ctrl, Alt, ...), use the platform-independent modifiers: M1, M2, M3.
    • M1 binds to Ctrl on Windows and Command on OS X.
    • M2 binds to Shift on both Windows and OS X.
    • M3 binds to Alt on Windows and Option on OS X.
  • CM key bindings should not conflict with key bindings already defined by the Eclipse platform


  • If a button launches a dialog or wizard, its label should end with an ellipsis (...) For example, "Add..."
  • Modifier buttons
    • These are buttons that require a table row to be selected to perform their action (e.g. Edit or Remove)
    • Modifier buttons should be initially disabled, and enabled once the user has selected a table row.

Date/Time Display

  • Date values should be displayed using DateFormat.MEDIUM (MMM dd, yyyy in the mockups)
  • Date/time values should be displayed using (DateFormat.MEDIUM, DateFormat.SHORT) (hh:mm AM/PM in the mockups)
  • Date text entry fields should have the tooltip "Sample date format: <format>"
  • Date/time text entry fields should have the tooltip "Sample date/time format: <format>"


  • Dialog size should not be set explicitly.
  • Error validation:
    • Dialogs should use field level validation.
    • The global error message for a dialog will not be used to display field level validation errors because there is no guarantee that it would display the message for the last edited field.
    • If there is a field validation error, the dialog OK/Save button should be disabled until the user corrects the error.


  • Editors should be
    • Resizable (default behaviour)
    • Moveable (default behaviour)
    • Closeable (default behaviour)
  • For guidelines on sections within editors, see "Sections" below.
  • Dirty state
    • Any change to an editable field in an editor should put the editor in a dirty state, indicated with an asterisk * in the editor title
    • This includes adding, editing, and removing items to/from tables in editor pages
    • The only exceptions to this are
      • Changes to items that open up in their own editors (e.g. a SKU in a multi-SKU product).
      • Addition of leading/trailing whitespace

Field Validation

  • Field validation should ignore leading/trailing whitespace

Field Presentation

  • Ensure that a text field is long enough to contain the maximum likely length of its value.
  • Fields that are editable:
    • Indicate a required field with an asterisk * before the field label.
  • Fields that are not editable:
    • Do not indicate a required field with an asterisk * before the field label.
    • Do not have a border around field

Field Layout

  • Spinners should not grab available horizontal space.

Field Values

  • Category, Product and SKU codes
    • Should only allow alpha numeric characters and hyphens '-'.
    • Have a max length of 255 chars.
    • Special characters (excluding hyphens) are not allowed, e.g. !@#$%^&*()<>?;:|{}[]


  • Contextual (right-click) menus should provide actions related to the selection only (not global or presentation-related actions).

Naming conventions

  • Create/Delete vs. Add/Remove:
    • Operations on entities (e.g. customers, orders, products) should use the labels "Create" and "Delete"
    • Operations on entity attributes (e.g. customer addresses, order shipments) should use the labels "Add" and "Remove"


  • There will be no search result pagination in the Administration perspective.
    • In all other perspectives, pagination controls should be incorporated into every search result view, as well as into the Product Listing view in Catalog perspective.
  • The number of results per page will be set by default to a global value (either 10 or 20, depending on product performance testing) configurable via the CM config file.
    • This default will be configurable via the Preferences menu.
  • The First and Previous pagination arrows should be disabled for the first page of results
  • The Next and Last pagination arrows should be disabled for the last page of results


  • In general, CM users should have at least read permissions for all screens in the application
  • The exception to this is the Administration perspective, where all permissions are on a plugin basis
    • A user either has edit permissions or no permissions for a plugin
    • If the user has no permissions for a plugin, it is hidden
  • In other perspectives, permissions are applied as follows:
    • In list views that have actions associated with them, permissions to edit and delete items are controlled on an item by item basis
      • If the user has no permissions for these operations, the associated actions should be automatically disabled
    • In editors, edit permissions may be controlled on a page or field basis
      • The UI mockups provide Edit and View versions of every editor page that has different permissions levels
      • These represent the page as seen by a user with maximum (full edit) and minimum (no edit) permissions, respectively


  • All search fields should allow spaces to be entered before or after the user's input.
    • The spaces should be trimmed before the search query is submitted.
  • The Clear button in search views should only clear the contents of the fields in the search view
    • If there are any results from a previous search displayed in the search results view, these should not be cleared.
  • Progress indication for long-running search
    • For long-running searches (longer than 800 ms) a modal progress dialog should display, similarly to this code example

Search results

  • In addition to search results views, the guidelines below also apply to the Product Listing view in the Catalog perspective
  • If there are no search results, a warning (not an error) should be displayed at the top of the search results view
    • In this case, the results of the previous search should be cleared
    • For an example of this behaviour, see the Customer Search Results view in the production application
  • Search results tables should support single click to select a row, double click to open its corresponding entity in an editor (see Tables section below)
  • If there are actions in the search results view that require a result to be selected, these should be initially disabled and enabled only if a result table row is selected (similarly to modifier buttons - see Buttons section above).


  • Sections should be expandable/collapsible if their number on the screen is potentially large (e.g. shipment sections in Fulfillment > Order Details).
  • Otherwise, sections should not be expandable/collapsible.
  • Sections should not contain a description unless specified in the UI mockups.


  • Table columns should all be left aligned (this is due to rendering issues for center/right alignment on Windows Vista).
  • Table height should not be set explicitly.
  • Table look and feel (based on the Sun Java UI guidelines):
    • Tables that are editable should use grid lines
    • Tables that are non-editable should use background striping for even-numbered rows
    • If a non-editable table has a single column, it should not use background striping
  • Tables should support the following events (except if they are inline editable - see next point):
    • Single click: Select row, unless the table is directly editable
    • Double click: Open the entity corresponding to the row in an editor or an Edit... dialog (as applicable)
      • For tables in editors, the double click behavior should be equivalent to single clicking a row and clicking on the Edit... modifier button next to the table
  • Selection models
    • If a table has modifier buttons (see Buttons section above), it should support row highlighting on selection (default behaviour)
    • If a table does not have modifier buttons, it should hide its selection (i.e. provide no row highlighting on selection)

Table Cells

  • Inline editable table cells should be indicated by a small "pencil" icon
  • Inline editable table cells should support the following events:
    • Single click: Select the current item and put the cell into edit mode or bring up a dialog to edit cell contents.
    • Double click: Not applicable
  • Changes to the cell value should be committed once a user clicks off the cell or hits the ENTER key.
  • Selection should be cancelled when user hits the "Esc" key.


  • All views should be resizable (default behaviour)
  • All views should be movable (default behaviour)
  • Left side navigation views should not be closeable
    • When creating views, need to call:
  • All other views should be closeable (default behaviour)


  • Use a wizard for any task consisting of many steps, which must be completed in a specific order.
  • Each wizard must contain a header with a banner graphic and a text area for user feedback.
  • A wizard should contain Back, Next, Finish, and Cancel buttons in the footer.
  • When a wizard first opens, the focus should be placed in the first field requiring information.
  • A wizard should display a prompt when information is absent, and an error when information is invalid.
  • Error validation:
    • Wizards should use field level validation.
    • The global error message for a wizard page will not be used to display field level validation errors because there is no guarantee that it would display the message for the last edited field.
    • If there is a field validation error, any Next/Finish buttons should be disabled until the user corrects the error.