UX guidelines for theme app extensions

A great customer-facing and merchant user experience (UX) is important to the success of our merchants.

Key principles for app blocks

The following are key principles for designing your app blocks:

  • App blocks are responsive to the size of the section to which they're added.

  • App blocks inherit styling properties from the theme, such as typography and colors.

  • App blocks can use autofill resource settings to automatically point to dynamic sources and ensure that content remains in sync with its parent section.

Merchant customization

Merchants need to be able to easily customize your app blocks and app embed blocks using the theme editor.

Don't clutter the theme editor with configurable settings. Limit these to visual settings, where possible. This is especially important for your app embed blocks. All app embed blocks will live in the same panel, and many configurable settings for an individual app embed block can quickly clutter the panel.

Let merchants do the following from the theme editor's Apps section:

  • Add, remove, or reposition your app's individual app blocks

  • Edit the settings for your app's individual app blocks

  • Preview edits before saving and publishing changes

Let merchants do the following from the theme editor's App embeds section:

  • Activate and deactivate your app's individual app embed blocks

  • Edit the settings for your app's individual app embed blocks

  • Preview edits before saving and publishing changes

Descriptions for public apps

Descriptions for apps sold on the Shopify App Store should indicate whether the app requires an Online Store 2.0 theme. This will prevent merchants from installing an app and discovering that the app doesn't work in their online store.

Merchant onboarding

On the app onboarding page in Shopify admin, give merchants clear post-installation onboarding instructions. To learn more about writing effective help documentation, refer to Help documentation in Shopify Polaris.

Provide merchants with the following information:

  • What app blocks and app embed blocks are in your app, and what they do

  • How to add, remove, and reorder your app's app blocks

  • How to activate and deactivate your app's app embed blocks

  • How to configure functional settings for your app's app blocks and app embed blocks

  • What templates your app's app blocks and app embed blocks can be added to

  • If desired, provide merchants with a deep link into the theme editor with an app embed block activated. Follow these guidelines for deep linking:

    • Ask merchants for the theme in which they want to activate the app embed block.
    • When deep linking into the App Embeds panel, inform merchants of the supported templates so that they know where the app embed block will be activated.
    • Inform merchants that they can customize positioning and other visual settings within the theme editor.
    • Include a Preview in theme call to action button for the deep link. For example:

      Example of a call to action button labeled Preview in theme

Uninstalling apps

When merchants uninstall apps, blocks associated with the apps need to be automatically and entirely removed from online store themes.