Merge pull request #86 from AdobeDocs/abs72485/ux-guidelines-ia

UX Guidelines

gatsby-config.js

@@ -527,8 +527,50 @@ module.exports = {
             path: "guides/design/",
           },
           {
-            title: "User interface guide",
-            path: "guides/design/user_interface.md",
+            title: "UX Guidelines",
+            path: "guides/design/ux_guidelines/introduction.md",
+            pages: [
+              {
+                title: "Introduction",
+                path: "guides/design/ux_guidelines/introduction.md",
+              },
+              {
+                title: "Design Principles",
+                path: "guides/design/ux_guidelines/design_principles.md",
+              },
+              {
+                title: "Theming",
+                path: "guides/design/ux_guidelines/theming.md",
+              },
+              {
+                title: "Visual Elements",
+                path: "guides/design/ux_guidelines/visual_elements.md",
+              },
+              {
+                title: "Feedback & Messaging",
+                path: "guides/design/ux_guidelines/feedback_and_messaging.md",
+              },
+              // {
+              //   title: "Mobile UX",
+              //   path: "guides/design/ux_guidelines/mobile_ux.md",
+              // },
+              {
+                title: "Branding Guidelines & Distribution",
+                path: "guides/design/ux_guidelines/branding_guidelines.md",
+              },
+              {
+                title: "Resources & References",
+                path: "guides/design/ux_guidelines/resources_and_references.md",
+              },
+              {
+                title: "Changelog",
+                path: "guides/design/ux_guidelines/changelog.md",
+              },
+            ],
+          },
+          {
+            title: "Implementation guide",
+            path: "guides/design/implementation_guide.md",
           },
           {
             title: "Best practices",

src/pages/guides/design/user_interface.md → src/pages/guides/design/implementation_guide.md

@@ -1,32 +1,10 @@
-import '/src/styles.css'
+# Implementation Guide
 
-# Design Overview
-
-The design of your add-on is just as important to the success of your add-on as the features it provides. This design section is provided to help lead you through the design process with useful guidelines, tips and resources.
-
-<TextBlock slots="heading, text, buttons" theme="light" isCentered/>
-
-## UX Guidelines
-
-Check out our UX Guidelines, which have been created with the intention to help developers closely align the design of their add-ons with the Adobe brand, providing an improved, unified experience for the end-user.
-
-- [UX Guidelines](https://xd.adobe.com/view/urn:aaid:sc:US:fd638450-1af8-49c3-ad29-0e76c2a2136f/)
-
-<InlineAlert slots="text" variant="success"/>
-
- We encourage all developers to review the new UX guidelines and incorporate them into your add-on design process. Doing so will provide the benefit of rapid development, increased adoption, and an overall more positive user experience. Please check back often as these guidelines will continue to be updated frequently.
-
-## Introduction
-
-Watch this short introductory video, then read on for more details. <br/><br/>
-
-<div style="display: flex; justify-content: center;">
-    <iframe width="560" height="315" src="https://www.youtube.com/embed/E9atPm5djco?si=QbafmhPAKJa6R4rI" title="Designing Add-on Interfaces" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
-</div>
+This section will help you implement the concepts and best practices outlined in the UX Guidelines.
 
 ## Spectrum Design System
 
-Adobe provides the [Spectrum Design System](https://spectrum.adobe.com/) which contains a comprehensive set of design guidelines, components and tools to help designers create a consistent user experience across products. Leveraging Spectrum in your add-on allows you to take advantage of all of the built-in benefits it provides while saving front-end development time. There are a few different implementations of Spectrum that are outlined in the sections below for reference, and in order of preferred use.
+Leveraging Spectrum in your add-on allows you to take advantage of all of the built-in benefits it provides while saving front-end development time. There are a few different implementations of Spectrum that are outlined in the sections below for reference, and in order of preferred use.
 
 <InlineAlert slots="text" variant="info"/>
 
@@ -145,7 +123,7 @@ Check out the [code samples](../../samples.md) in the contributed folder for **S
   - **react-aria**: a library of React hooks implementing the patterns defined in the ARIA practices spec, including mouse, touch, and keyboard behavior, accessibility, and internationalization support
   - **react-stately**: a library of React hooks implementing cross platform (e.g. web/native) state management for components that need it.
 
-<InlineAlert slots="text" variant="warning"/>
+<InlineAlert slots="text" variant="info"/>
 
 We recommend using [**swc-react**](https://opensource.adobe.com/spectrum-web-components/using-swc-react/) over [React Spectrum](#react-spectrum) in your add-ons based on React, because it currently offers a more comprehensive set of components which provide built-in benefits as detailed above in the [Spectrum Web Components section](#spectrum-web-components), and is more actively supported.
 
@@ -257,7 +235,7 @@ Use the existing Adobe Express UI as an example of the types of patterns and beh
 <InlineAlert slots="text" variant="success"/>
 
 **Color Picker Component Tip:**
-If you're using the native browser color picker, it looks slightly different in every browser and doesn't fit the Express theme by default. You can make this control look more like Spectrum with CSS as [illustrated in this codepen](https://codepen.io/kerrishotts/pen/QWZazJP) for reference.
+If you're using the native browser color picker, it looks slightly different in every browser and doesn't fit the Express theme by default. You can make this control look more like Spectrum with CSS as [illustrated in this codepen](https://codepen.io/kerrishotts/pen/QWZazJP) for reference, or borrow the code used in [this guide](../tutorials/grids-addon.md#coding-the-grids-add-on).
 
 ## Using Fonts
 

src/pages/guides/design/index.md

@@ -8,7 +8,7 @@ The design of your add-on is just as important to the success of your add-on as
 
 ## Introduction
 
-This set of design guides are provided to help lead you through the design process of your add-on and include useful guidelines, tips and resources. First, we encourage you to watch this short video about designing your add-on interface, then read on for more details. <br/><br/>
+This set of design guides is provided to help lead you through the design process of your add-on and includes useful guidelines, tips, and resources. First, we encourage you to watch this short video about designing your add-on interface, then read on for more details. <br/><br/>
 
 <div style="display: flex; justify-content: center;">
     <iframe width="560" height="315" src="https://www.youtube.com/embed/E9atPm5djco?si=QbafmhPAKJa6R4rI" title="Designing Add-on Interfaces" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>  

src/pages/guides/design/ux_guidelines/branding_guidelines.md

@@ -0,0 +1,51 @@
+---
+keywords:
+  - Adobe Express
+  - Express Add-on 
+  - Extend
+  - Extensibility
+  - User Interface
+  - User Experience
+  - UI
+  - UX
+  - Guidelines
+  - Branding
+title: Branding Guidelines
+description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
+contributors:
+  - https://github.com/undavide
+---
+
+# Branding Guidelines
+
+When creating your add-on, a distinct and consistent brand identity is your ticket to a lasting impression.
+
+This section focuses on key aspects of branding, like Icon and Publisher Logo design, as well as best practices for incorporating promotional images (screenshots or illustrations) for the Adobe Express add-on Marketplace.
+
+Please refer to the [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf) for comprehensive details on integrating Adobe branding, including when and how to use Adobe logos, product names, and terms.
+
+## Add-on Icon
+
+The add-on's icon should be original, suitable for different devices and browsers, and not violate the [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf). Please request a written license agreement from Adobe if you wish to use any Adobe logo, product icon, or image in your preview and feature graphics, product icons, or website.
+
+Three sizes are required for the add-on's icon: **36x36**, **64x64**, and **144x144** pixels as PNG or JPG files.
+
+![add-on icon](./img/branding_add-on-icon.png)
+
+## Publisher Logo
+
+The publisher's logo is only required the first time you [submit for distribution](/guides/distribute/public-dist.md#2-prepare-your-assets), in case you've never created a publisher profile before. It should be a square, **250x250** pixels PNG or JPG file.
+
+![publisher logo](./img/branding_publisher-logo.png)
+
+## Imagery
+
+When creating a [public listing](../../distribute/public-dist.md) for the Adobe Express add-on Marketplace, you can provide promotional images, such as screenshots and illustrations. At least one is required.
+
+![screenshots and illustrations](../../distribute/img/public-listing-screenshots-v2.png)
+
+### Screenshots and illustrations
+
+Any image used in your listing must comply with the [Developer Brand Guidelines](https://developer.adobe.com/express/embed-sdk/docs/assets/34359598a6bd85d69f1f09839ec43e12/Adobe_Express_Partner_Program_brand_guide.pdf). They should accurately depict the add-on's functionality and features and not contain any misleading information or inappropriate content. The recommended image size is **1360x800** pixels, as PNG or JPG.
+
+![screenshots and illustrations](./img/branding_screenshot.png)

src/pages/guides/design/ux_guidelines/changelog.md

@@ -0,0 +1,28 @@
+---
+keywords:
+  - Adobe Express
+  - Express Add-on 
+  - Extend
+  - Extensibility
+  - User Interface
+  - User Experience
+  - UI
+  - UX
+  - Guidelines
+  - Branding
+title: Changelog
+description: UX Guidelines Changelog.
+contributors:
+  - https://github.com/undavide
+---
+
+## Changelog
+
+### 8 October 2024
+
+- Created a new web version of the Adobe Express add-on UX Guidelines.
+- Integrated the existing content from the Adobe XD document into the new structure. The old version is [available here](https://xd.adobe.com/view/urn:aaid:sc:US:fd638450-1af8-49c3-ad29-0e76c2a2136f/) as a reference.
+
+### 28 August 2023
+
+- Last update to the Adobe XD document version of the Adobe Express add-ons UX Guidelines.

src/pages/guides/design/ux_guidelines/design_principles.md

@@ -0,0 +1,41 @@
+---
+keywords:
+  - Adobe Express
+  - Express Add-on 
+  - Extend
+  - Extensibility
+  - User Interface
+  - User Experience
+  - UI
+  - UX
+  - Guidelines
+  - Design Principles
+title: Design Principles
+description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
+contributors:
+  - https://github.com/undavide
+---
+
+# Design Principles
+
+When you're designing add-ons for Adobe Express, it's important to start with the principles that guide all of Adobe's products. They will be your roadmap, ensuring that what you create is not only visually appealing but also consistent, accessible, and user-friendly. Think of them as your toolkit for building something that looks great, works well, and fits seamlessly into the application.
+
+## Consistency: creating a cohesive experience
+
+You should design your add-ons to feel like a natural extension of the platform, conforming to Adobe Express's visual language: the Spectrum Design System. This coherence isn't just about visual elements but extends to interaction patterns and behaviours. Keeping everything aligned creates a smoother experience where users can easily navigate and understand your add-on, achieving their goals effortlessly.
+
+## Accessibility: designing for inclusion
+
+All add-ons you develop should be accessible to everyone, regardless of their abilities or circumstances. This includes considering elements like contrast and text size, as well as accommodating a broad spectrum of digital skills. An accessible design adapts to the user, offering clear and intuitive interactions, removing barriers, and making sure that every user can fully engage with it.
+
+## Usability: prioritizing ease of use
+
+Your add-on should be as easy to operate as it is powerful. Design it with users in mind so they can navigate it effortlessly, where each feature is clearly accessible and straightforward. Eliminate unnecessary steps and ensure that every interaction feels natural. Always provide feedback so users know what to expect and how to achieve their goals. The more intuitive the experience, the more likely they are to engage and rely on it over again.
+
+## Aesthetics: balancing form and function
+
+The aesthetic appeal of your add-on plays a significant role in the overall user experience: a pleasing design attracts more users and enhances their interaction with it. When the design is functional and visually charming, it creates an enjoyable experience and complements usability. Keeping the aesthetics aligned with Adobe's brand identity will reinforce the connection to the platform and tighten the overall user experience.
+
+## Bringing it all together
+
+By embracing these design principles, you'll build add-ons that integrate smoothly with Adobe Express and provide real value to users. Each concept works in harmony with the others; keep these guidelines in mind as you develop, and you'll create tools that are both effective and a pleasure to use. In the following pages, you'll find detailed recommendations, requirements, and best practices to help you apply these principles to your projects.

src/pages/guides/design/ux_guidelines/feedback_and_messaging.md

@@ -0,0 +1,78 @@
+---
+keywords:
+  - Adobe Express
+  - Express Add-on 
+  - Extend
+  - Extensibility
+  - User Interface
+  - User Experience
+  - UI
+  - UX
+  - Guidelines
+  - Feedback
+  - Messaging
+title: Feedback & Messaging
+description: This document provides an overview of the UX guidelines to follow when designing your Adobe Express add-on.
+contributors:
+  - https://github.com/undavide
+---
+
+# Feedback & Messaging
+
+Feedback and messaging are essential UX components. Your add-ons should always provide users with information about the state of the system, the results of their actions, and any errors that may have occurred.
+
+Unclear feedback and mishandled errors can lead to confusion and, crucially, are a cause of [rejection](../../../guides/distribute/rejections.md#error-handling) when submitting add-ons to the Adobe Express Marketplace. On the other hand, well-designed feedback can help users understand what is happening and what they need to do next.
+
+## Loading Indicators
+
+Loading indicators are particularly important when the system is processing a request that may take some time to complete; for instance, when fetching data from a server or authenticating a user. They show that the system is working and users should wait for the process to finish.
+
+### Progress Circles
+
+[Progress circles](https://spectrum.adobe.com/page/progress-circle/) show the progression of a system operation such as downloading, uploading, processing, etc. in a visual way.
+
+![Progress circles](./img/feedback_progress-circles.png)
+
+They can represent determinate or indeterminate progress: either the percentage of the operation that has been completed or spin indefinitely until completion.
+
+![](./img/feedback_progress-circles-animation-wide.gif)
+
+### Ghost Loading
+
+When a group of cards are loading, they follow the [ghost loading convention](https://spectrum.adobe.com/page/cards/#Ghost-loading).
+
+![](./img/feedback_ghost-loading.png)
+
+There are 5 phases for ghost loading:
+
+1. Card group (including metadata) ghost loads.
+2. If metadata for all cards is loaded before all preview images are loaded, the metadata is displayed for all cards as soon as the last piece of metadata loads. Previews continue to ghost-load.
+3. If all preview images load within a certain period (usually measured in seconds, which you need to specify depending on the use case), they are shown as soon as the last preview loads.
+4. If all previews have not finished loading at the end of the x period, the loaded previews are shown, and the pending previews each receive an individual progress circle. The group is no longer in a ghost-loading state.
+5. If the preview load times out, an error is shown along with a mechanism to retry loading.
+
+## In-line Alerts
+
+[In-line alerts](https://opensource.adobe.com/spectrum-css/inlinealert.html) display a non-modal message associated with objects in a view. These are often used in form validation, providing a place to aggregate feedback related to multiple fields.
+
+![](./img/feedback_ghost-loading.png)
+
+## Toasts
+
+[Toasts](https://spectrum.adobe.com/page/toast/) display brief, temporary notifications. They’re meant to be noticed without disrupting a user’s experience or requiring an action to be taken.
+
+![](./img/feedback_toasts.png)
+
+They come in multiple kinds, each with a different purpose:
+
+![](./img/feedback_toast-kinds.png)
+
+## Full-panel Messaging
+
+When the feedback is more complex or requires more space, a full-panel message can be used.
+
+![](./img/feedback_full-panel-messaging.png)
+
+Please mind the padding between the graphics, text and other UI elements to ensure a clear and organized layout.
+
+![](./img/feedback_full-panel-messaging-padding.png)