diff --git a/doc/contributor-guide/source/user-guidelines.rst b/doc/contributor-guide/source/user-guidelines.rst index d29e8958f5..3013843b66 100644 --- a/doc/contributor-guide/source/user-guidelines.rst +++ b/doc/contributor-guide/source/user-guidelines.rst @@ -21,7 +21,6 @@ and techniques in the following sections: :maxdepth: 2 ux-ui-guidelines/ux-personas.rst + ux-ui-guidelines/gui-guidelines.rst ux-ui-guidelines/ui-text-guidelines.rst -.. TODO ux-ui-guidelines/gui-guidelines.rst - diff --git a/doc/contributor-guide/source/ux-ui-guidelines/gui-guidelines.rst b/doc/contributor-guide/source/ux-ui-guidelines/gui-guidelines.rst new file mode 100644 index 0000000000..fc657251c2 --- /dev/null +++ b/doc/contributor-guide/source/ux-ui-guidelines/gui-guidelines.rst @@ -0,0 +1,241 @@ +============== +GUI guidelines +============== + +Principles +~~~~~~~~~~ + +The following principles describe concepts that help drive GUI development. +They are also designed to avoid common issues. + +.. note:: + + The following principles are recommendations only, it is at your discretion + whether or not to use and implement these guidelines. + +For the purpose of this document, and to avoid confusion, the following +terms will be defined: + +Modal + A modal window is a graphical control element subordinate to an + application's main window. +Workflow + A workflow that describes the steps to complete an action. + + +Design to scale +--------------- + +Your designs should reflect production environments rather than development +environments. +For example, a production environment can have fifty images rather than the +three included in devstack. Using a control that is appropriate for three +images can impact the usability associated with production environments. + +For example: + +* Instances: 2,000 +* Images: 50 +* Projects: 2,000 +* Users: 1,000 +* Operators: 8 +* Regions: 8 + +Use cases +--------- + +Open source developer-driven projects do not always consider the end user when +creating products. Educating and helping novices to complete a resource is +vital. There are two assumptions within the community: + +#. Novices users require a GUI +#. Advanced users use a CLI or API + +Ensure workflows provide enough information for users to drive the decision- +making process. We recommend referring to the OpenStack personas when +designing and creating. The personas are: + +* :ref:`arnie-infrastructure-arch` +* :ref:`carlos-cloud-ops` +* :ref:`doug-domain-operator` +* :ref:`pei-project-owner` +* :ref:`alan-app-developer` + +Specific use case interfaces vary based on the individual use case. +For example, a GUI may be appropriate to launch 1-x of the same instance, but +difficult for multiple instances that are different. + +See :ref:`ux-personas` for more information. + +Mandatory parameters +-------------------- + +Mandatory parameters are the minimum parameters required to create a resource. +This is especially important for complex nested resources, like load balancers +or networks. Mandatory parameters allow users to create resources without +being intimidated by a significant number of steps. We suggest creating the +top level resource and then send the user to the network details page. + +The 80% rule is a software framework that ensures 80% of use cases are +easy to implement, and 20% of use cases are difficult to implement. We +recommend using mandatory parameters to encourage designers and developers +to keep to the 80% rule when creating a workflow. + +.. note:: + + Using mandatory parameters assumes that users are able to add + parameters in the resource. + + +Patterns +~~~~~~~~ + +The following patterns provide GUI frameworks to assist designers and engineers +to create interfaces that are consistent across OpenStack products. + +For example, the horizon project chooses to use ``bootstrap``. +See `Styling in Horizon (SCSS) `_ +for more information. + +Cancel buttons +-------------- + +On modals, the cancel button should be located at the bottom left and +the ``X`` to close should be located at the top right. + +Modal error messages +-------------------- + +When canceling a modal that has forms that are partially completed, +we recommend a warning should be displayed at the top center of the modal. + +.. note:: + + Any error message displayed should be inside the corresponding modal to + avoid GUI conflicts. + +A red background and a warning icon on the top left are also recommended. + +For more information on guidelines for UI text, see: +``_. + +Wizards +------- + +A software wizard presents a workflow and helps users through it. The +``Back`` and ``Next`` buttons should be located at the bottom and to the +right of the modal, but to the left of the create button. The ``Back`` +button should be disabled, instead of invisible. Initially, the ``Create`` +button should remain disabled until the mandatory parameters have been +provided. All required items should have an asterisk on the right. + +Page errors +----------- + +Any error messages should be displayed on the upper right corner of the +browser. A counter should be displayed for error messages that persist for +a certain number of seconds. All error messages should close by pressing +the ``X`` on the upper right corner of the message. + +.. note:: + + The error message height should vary to fit the content. + +For more information on guidelines for UI text, see: +``_. + +Actions +------- + +Global actions should align to the top right and be placed on the top +of the table. For example, the ``Launch Instance`` button is a global +table action. + +Batch actions, which apply to single or multiple rows, should align to +the left and be above the rows' checkboxes. + +Control actions should align to the right of the row. In addition, +checkboxes should align to the left of each row and be used for deleting +single or multiple rows. + +Search +------ + +There are typically two search box types within GUIs. There is the global +search, which applies to all pages, and local (panel) search box, which +searches within pages. We recommend global search boxes be located in the +masthead, and the local (panel) search be located within the page. + +.. note:: + + Using the search boxes interchangeably can cause confusion as it is not always + clear what is being searched. + +Icons +----- + +We recommend using the following icons from +`Font Awesome `_ with the corresponding meaning. + + +`Create `_ + The create icon is used for global actions, such as launch instance or + create volume. No other icons, such as ‘upload to cloud’, should be + used with global actions. + +`Delete `_ + The delete button should be used with any destructive actions + including, global, batch, and control actions. + +`Warning `_ + Use the warning icon to ensure the user is aware that data will be + lost if they proceed with an action. For example, canceling out of a + modal even if the user has completed some of the forms. In addition, + it should indicate that a resource is unusable. For example, use the + warning icon to indicate that a flavor cannot be used because all + available quota for a project has been consumed. + +Expand and collapse + The following icons should be used to allow users to either expand or + collapse when viewing additional information for a resource. This icon + should be used instead of the ``+`` and ``-`` icons. + `Expanded `_ + `Collapsed `_ + +`Help `_ + Use the help icon when referring the user to additional + content that provides additional information. + +Download and upload files + These icons should be used when the user is either uploading a file, + such as an image, or downloading files, such as a key pair. However, + it should not be used for global actions such as launching an instance. + `Download `_ + `Upload `_ + +`Cancel `_ + The cancel icon should be used for any actions where the user would + want to exit a workflow. For example, when you are exiting a wizard, + there should be an ``X`` in the top right of the modal. + This icon should not be used for destructive actions, such as delete. + +`Search `_ + Whether searching globally or within a panel, the search icon + should always be on the inside and aligned to the left of any + text boxes. + +Accessibility +~~~~~~~~~~~~~ + +We recommend using :abbr:`ARIA (Accessible Rich Internet Applications)` +when developing content to ensure accessibility is accounted for +appropriately. + +ARIA defines ways to make web content and web applications, especially those +developed with Ajax and JavaScript, more accessible to people with +disabilities. +For example, ARIA enables accessible navigation landmarks, JavaScript widgets, +form hints and error messages, live content updates, and more. + +For more information, visit: ``_. +