From 977a1e92bdb7d586b62a19fae543feb6ced0bbad Mon Sep 17 00:00:00 2001
From: Alexandra <alexandra.settle@rackspace.com>
Date: Fri, 22 Jul 2016 10:16:10 +0100
Subject: [PATCH] [contrib-guide] Adding GUI guidelines section to UX content
Change-Id: I511455217593b3fbd59672e37010ad76dc9d3caf
Closes-bug: #1603420
---
.../source/user-guidelines.rst | 3 +-
.../ux-ui-guidelines/gui-guidelines.rst | 241 ++++++++++++++++++
2 files changed, 242 insertions(+), 2 deletions(-)
create mode 100644 doc/contributor-guide/source/ux-ui-guidelines/gui-guidelines.rst
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) <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>`_.
+