[contrib-guide] Adding GUI guidelines section to UX content
Change-Id: I511455217593b3fbd59672e37010ad76dc9d3caf Closes-bug: #1603420
This commit is contained in:
Alexandra
Joseph Robinson
parent
4a6d8b05f7
commit
977a1e92bd
@ -21,7 +21,6 @@ and techniques in the following sections:
|
|||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
ux-ui-guidelines/ux-personas.rst
|
ux-ui-guidelines/ux-personas.rst
|
||||||
|
ux-ui-guidelines/gui-guidelines.rst
|
||||||
ux-ui-guidelines/ui-text-guidelines.rst
|
ux-ui-guidelines/ui-text-guidelines.rst
|
||||||
|
|
||||||
.. TODO ux-ui-guidelines/gui-guidelines.rst
|
|
||||||
|
|
||||||
|
|||||||
241
doc/contributor-guide/source/ux-ui-guidelines/gui-guidelines.rst
Normal file
241
doc/contributor-guide/source/ux-ui-guidelines/gui-guidelines.rst
Normal file
@ -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) <http://docs.openstack.org/developer/horizon/topics/styling.html>`_
|
||||||
|
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:
|
||||||
|
`<http://docs.openstack.org/contributor-guide/ui-text-guidelines.html>`_.
|
||||||
|
|
||||||
|
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:
|
||||||
|
`<http://docs.openstack.org/contributor-guide/ui-text-guidelines.html>`_.
|
||||||
|
|
||||||
|
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 <http://fontawesome.io>`_ with the corresponding meaning.
|
||||||
|
|
||||||
|
|
||||||
|
`Create <http://fontawesome.io/icon/plus/>`_
|
||||||
|
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 <http://fontawesome.io/icon/trash/>`_
|
||||||
|
The delete button should be used with any destructive actions
|
||||||
|
including, global, batch, and control actions.
|
||||||
|
|
||||||
|
`Warning <http://fontawesome.io/icon/exclamation-triangle/>`_
|
||||||
|
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 <http://fontawesome.io/icon/chevron-down/>`_
|
||||||
|
`Collapsed <http://fontawesome.io/icon/chevron-right/>`_
|
||||||
|
|
||||||
|
`Help <http://fontawesome.io/icon/question-circle/>`_
|
||||||
|
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 <http://fontawesome.io/icon/download/>`_
|
||||||
|
`Upload <http://fontawesome.io/icon/upload/>`_
|
||||||
|
|
||||||
|
`Cancel <http://fontawesome.io/icon/times/>`_
|
||||||
|
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 <http://fontawesome.io/icon/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: `<https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA>`_.
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user