[meta] Update and improve linking to Human Interface Guidelines docs

Problem/Motivation

On #2293627: [meta] Document Human Interface Guidelines and make Seven style guide, there was a discussion of making a Seven theme visual style guide, and it got mixed up into a discussion of making a better Human Interface Guidelines (HIG) document. On comment #42 & #43, we decided these two goals were not really the same, and that we needed to start over with two new issues. This one is about the HIG. See #2404111: [Meta] Create a visual style guide for the Seven theme for the Seven Style Guide.

Background and motivation

As we spend a great deal of time working on the direction of Drupal, we are constantly aware of the fact that contributed modules of Drupal often do not follow the same interface standard that we apply in core. To assure we get a consistent user experience when one uses up to 30 modules on a site, which is a common use case – we need more documentation around our interface patterns: We need a "Human Interface Guidelines" (HIG) document, which would document design patterns:

A design pattern is a repeatable design solution, that’s been tested, reviewed, and verified – James Refell, UI Design Manager, Ebay Inc.

Also, we performed research under core developers, module maintainers and designers back in 2009 on if there should be a pattern library, and what they then expect to find in such a library. The results of this study can be found in the attached PDF..

Past attempts

• We had an HIG document for Drupal 7 (http://drupal.org/ui-standards), but few actual contrib users used and followed it.
• We had a design test module in Drupal 8 that was unused #2037569: Remove design_test module

Audience, Goals, Etc.

In thinking about how to provide an HIG, the first step is to ask the questions you'd normally ask as part of any web site strategy discussion:

1. Who the audience is (primary, secondary?).
2. What information the audience would be looking for.
3. What information you want them to get in this guide, in addition to or instead of what they think they're looking for.
4. How best to organize and present the information so that the audience can find the information they/you want/need.
5. Any other concerns?

We discussed this question in the issue comments below, and here are the answers (see especially #24, #30, and #31):

1. Audience -- there are several audiences:
   • Core developers: They have to learn about new patterns that we set.
   • Contrib developers (modules, themes with settings UI, etc.): They have to abide by patterns that we set and learn how to make their UI more usable
   • (UX) Designers: They need to know we have these, understand them when talking to their developers. But also learn about them as its a sign of design maturity.
   • Project/sales managers: They can tell their clients that the module is developed after standards, both API and UI.
2. What the audience thinks they are looking for: See the rattached PDF.; to summarize, developers need several levels of information:
   • High level: What kind of pages should I create? (such as listing, creation, and settings pages; often driven by technical implementation, but not always)
   • High level: How should people find and navigate my pages? (tabs, actions, menu links, etc.)
   • Detailed level: What design pattern should I use on a particular UI page? (fieldset, vertical tab, button, ...)
   • Detailed level: How do I actually put this design pattern on a particular UI page?
   • Detailed level: How can I optimize my labels/text?
   • Even more detailed level: I want to use a #type = 'foo' or #theme = 'bar' render element on my page. What are the properties I need to set?<?li>
3. Our goals:
   • Consistency in the UI across contrib and core, so that we have a uniform, accessible, usable UI for the entire Drupal ecosystem.
   • Understanding that using the provided components is easy, so that writing custom HTML/CSS seems like a pain in comparison.
4. Presentation:
   • Developers need to discover this document, so that when they're looking for "How to make a button" (or fieldset or whatever) they are guided towards the "should you really be using this button or whatever here at all" information and the "how to make it consistent" information as well.
   • Needs to be incredibly concise, as UI is clearly not the main focus of developers
   • Visual demos are helpful.
   • Needs to include or link to the "how to" implementation details.
   • Should not present HTML/CSS markup for developers to copy/paste; instead, present the proper way of doing things: YML files for local actions/links and menus, and render array elements for the rest.
   • Needs sections telling how to choose the UI pattern for different purposes.
   • Needs sections on overall generic design principles.
   • Needs text guidelines section.
   • Organization by UI pattern seems helpful for the details sections.
   • An index by render/form element type would also be useful, since developers may approach finding the information this way, and if they're looking for the details of a particular render element, we'd like them also to learn about how to use them The Right Way and At The Right Time.
5. Other concerns:
   • Maintainability - Guide should be easy to maintain

Proposed resolution

Improve the existing HIG

a) We already have an HIG on drupal.org, at http://drupal.org/ui-standards -- but it was written for Drupal 7. It needs to be:
- Updated for Drupal 8, without losing Drupal 7.
- Edited as necessary to align with the goals and audience, so that developers looking for the information they want/need will locate this information that we want them to find.
- This means it needs to have implementation details added, to tell developers how to make a UI that conforms to the HIG in Drupal 8 (*.*links.yml files, #type or #theme in render arrays, etc.). We should include both D7 and D8 implementation details.

Increase developer knowledge that the HIG exists

b) Make an overview topic on HIG, using @defgroup for api.drupal.org, linked from the api.d.o landing page for Drupal 8. Make sure that links to the drupal.org page/section in (a).

c) Add links from various topics and classes in Drupal Core to relevant sections of the HIG on drupal.org. For instance, any docs about making tables should link to the HIG page about tables, and probably also have a few UI guidelines included as an opener... It will take some work to find these links and make patches, but it should increase the visibility of the HIG.

d) When we figure out what to do about a Form and Render API reference for Drupal 8, make sure that it has links to the HIG and relevant sections as well. See #1617948: [policy for now] New standard for documenting form/render elements and properties

Remaining tasks

See Proposed Resolution.

Beta phase evaluation

This applies to child issues. Copy and paste...

User interface changes

None.

API changes

None.