diff --git a/SUMMARY.md b/SUMMARY.md index f0e2e3cc..592d5008 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -108,7 +108,7 @@ * [Contextual Bar](apps-engine/user-interface/uikit/opening-the-contextual-bar.md) * [Building Blocks](apps-engine/user-interface/uikit/building-blocks.md) * [Action Buttons](apps-engine/user-interface/uikit/action-buttons.md) - * [Surface Guidelines](apps-engine/ui-guidelines.md) + * [Apps-Engine UI Guidelines](apps-engine/user-interface/apps-engine-ui-guidelines.md) * [Permission System](apps-engine/permission-system.md) * [App Data Persistence](apps-engine/app-data-persistence/README.md) * [Managing Internal State](apps-engine/recipes/managing-internal-state.md) diff --git a/apps-engine/ui-guidelines.md b/apps-engine/ui-guidelines.md deleted file mode 100644 index 313a0b15..00000000 --- a/apps-engine/ui-guidelines.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -description: >- - Follow these guidelines for any interface you are creating for your - Rocket.Chat App using the Apps Engine. ---- - -# Surface Guidelines - -Follow these guidelines for any interface you are creating for your Rocket.Chat App using the Apps Engine. - -## Surface Types - -There are two surfaces types: - -1. **Simple**: Simple surface types are examples like menus that can contain only the predefined list of menu items -2. **Complex**: Examples like contextual bars and modals which can use all available [UiKit ](broken-reference)components to build the intended user experience. - -## User Menu - -The user menu contains items specific to the user such as status and preferences. Every item on this menu should relate to a user. - -* **Do** add only user-specific items to this menu - -

User menu visual guide

- -## Room kebab menu - -The room kebab menu is located at the top right of any [Rocket.Chat Room](https://docs.rocket.chat/use-rocket.chat/user-guides/rooms). - -* This menu opens up a contextual bar and not a modal. -* Items on this menu must relate to or affect the current room or its context in some way. -* **Don't** include icons or use emojis in item labels. - -

Room kebab menu UI guide

- -## Message kebab menu - -The message kebab menu can be seen by the right of a message when hovered upon on a Desktop or long-pressed on a Mobile device. - -* The message kebab menu is reserved exclusively for items that affect the selected message. -* Only Rocket.Chat core actions can use icons. -* **Don't** include icons or emoji anywhere inside the item label. - -

Message kebab menu UI guide

- -## Chat messages - -* Make messages very clear, brief, and not long. -* **Do** use an emoji if only they help get the intended message across. -* **Don't** send messages on a user's behalf. -* **Don't** over-communicate or use emojis excessively. - -

Chat message UI Guide

- -## Slash commands - -Slash commands are usually the simplest ways users can interact with installed apps. - -* Slash command descriptions should appear by the side of the command when typed in the message composer. -* Commands must have hyphens between words and include a description. - -

Slash commands UI Guide

- -* All apps using a slash command must have a `/help` command showing the possibilities of the app and it's commands - -## Contextual bars - -Apps can utilize the contextual bar surface to offer information and actions to the user. - -* Contextual bars must contain a corresponding item in the [room kebab menu](ui-guidelines.md#room-kebab-menu). -* Contextual bar titles must use sentence case capitalization eg: `Google Calendar settings` not `Google Calendar Settings.` -* **Don't** use images, such as app icons, inside the contextual bar header. -* **Don't** use titled case in the contextual bar header. -* **Do** use sentence case in contextual bar header. - -

Contextual bar UI Guide

- -## Modals - -Apps utilize modal dialogs to present information and actions to the user. Use [Contextual bars](ui-guidelines.md#contextual-bars) for more complex and involved interactions. - -As a default setting, the app logo asset will be presented in modals that are linked to the corresponding app. - -* **Don't** use modals without the app name in the tagline. -* **Do** use the app name in the modal tagline. - -

Modals UI Guide

- -## App (bot) username - -If your app has an associated bot user, the username of that user must be identical to the app name except with `-` replacing any spaces in the app name. - -Eg if the app is Google Calendar app, the bot username must be _`@google-calendar`_\ -Not _`@google-calendar.bot`_ or any other variation. - -\ diff --git a/apps-engine/user-interface/apps-engine-ui-guidelines.md b/apps-engine/user-interface/apps-engine-ui-guidelines.md new file mode 100644 index 00000000..3613bae9 --- /dev/null +++ b/apps-engine/user-interface/apps-engine-ui-guidelines.md @@ -0,0 +1,87 @@ +# Apps-Engine UI Guidelines + +With the Apps-Engine UIKit, we have seen how to create the interactions in our apps which are displayed on the Rocket.Chat UI. You need to follow these guidelines for any interface that you are creating for your Rocket.Chat app using the Apps-Engine. + +## Surface types + +There are two surface types: + +1. **Simple**: Examples like menus that can contain only the predefined list of menu items +2. **Complex**: Examples like contextual bars and modal views can use all available [UIKit components](uikit/building-blocks.md) to build the intended user experience. + +## User menu + +The user menu contains items specific to the user such as status and preferences. Every item on this menu should relate to a user. + +* **Do** add only user-specific items to this menu + +

User menu visual guide

+ +## Room kebab menu + +The room kebab menu is located at the top-right side of any [Rocket.Chat Room](https://docs.rocket.chat/use-rocket.chat/user-guides/rooms). + +* This menu opens up a contextual bar and not a modal. +* Items on this menu must relate to or affect the current room or its context in some way. +* **Don't** include icons or use emojis in item labels. + +

Room kebab menu UI guide

+ +## Message kebab menu + +The message kebab menu can be seen on the right side of a message when hovered upon on a Desktop or long-pressed on a Mobile device. + +* The message kebab menu is reserved exclusively for items that affect the selected message. +* Only Rocket.Chat core actions can use icons. +* **Don't** include icons or emojis anywhere inside the item label. + +

Message kebab menu UI guide

+ +## Chat messages + +* Make messages very clear and brief. +* **Do** use an emoji if only they help get the intended message across. +* **Don't** send messages on a user's behalf. +* **Don't** over-communicate or use emojis excessively. + +

Chat message UI Guide

+ +## Slash commands + +Slash commands are usually the simplest ways users can interact with installed apps. + +* Slash command descriptions should appear next to the command when typed in the message composer. +* Commands must have hyphens between words and include a description. + +

Slash commands UI Guide

+ +* All apps using a slash command must have a `/help` command showing the possibilities of the app and its commands. + +## Contextual bars + +Apps can utilize the contextual bar surface to offer information and actions to the user. + +* Contextual bars must contain a corresponding item in the [room kebab menu](apps-engine-ui-guidelines.md#room-kebab-menu). +* Contextual bar titles must use sentence case capitalization eg: `Google Calendar settings`, not `Google Calendar Settings.` +* **Don't** use images, such as app icons, inside the contextual bar header. +* **Don't** use the title case in the contextual bar header. +* **Do** use sentence case in contextual bar header. + +

Contextual bar UI Guide

+ +## Modals + +Apps utilize modal dialogs to present information and actions to the user. Use [Contextual bars](apps-engine-ui-guidelines.md#contextual-bars) for more complex and involved interactions. + +As a default setting, the app logo asset will be presented in the modals that are linked to the corresponding app. + +* **Don't** use modals without the app name in the tagline. +* **Do** use the app name in the modal tagline. + +

Modals UI Guide

+ +## App (bot) username + +If your app has an associated bot user, the username of that user must be identical to the app name except with a hyphen replacing any spaces in the app name. For example, if the app is a Google Calendar app, the bot username must be _`@google-calendar`,_ not _`@google-calendar.bot`_ or any other variation. + +With these guidelines in mind, you can create functional apps that leverage the UIKit components and provide helpful user interactions. To fully apply these functionalities, you need to define the permissions for your app so that it can perform actions such as sending messages or modifying settings. Let's move on to the next section to understand the details of app permissions.