[meta] Document Human Interface Guidelines and make Seven style guide

Hooray, #2033211: Move Seven CSS files into css directory got in! Next step would be to Split the Seven CSS files into components.

D-Oh! A little too fast. #2033211: Move Seven CSS files into css directory got reverted.

+1

BTW, in July, I became a maintainer of kss-node. https://github.com/kss-node/kss-node/graphs/contributors

My vision for the future of that project is to have the CSS docs point at the template it wants to use for a component. Then a Drupal module (styleguide module? w/ drush?) could be configured to automatically run theme hooks and spit out the results into individual files. And those files would then be sucked in by kss-node.

So... I've taken a look at some of the patches, and Lewis's nice start at the documentation output, and I discussed this with Bojhan and others in IRC just now.

My overall conclusion is that this idea (adding comments in the Seven them CSS and parsing them with KSS) is a great way to document "This is how Drupal should take render arrays and make them into HTML/CSS for the Seven administrative theme".

However, the objective here is really to make Human Interface Guidelines (HIG) documentation for module developers, right? In this, I think the current idea does not work well.

The problem is that KSS is oriented towards HTML markup and the classes/IDs that CSS uses to style it. But a module developer should not even know about the HTML markup nor the CSS classes.

For instance, if they're making a table, they should be using

'foo' => array(
   '#type' => 'table',
...

in a render array. They should absolutely never be writing table HTML markup from scratch.

If they're making buttons, they should probably be either using one of the *.links.yml files to add them to the page at the top, or they should be using a #type = actions() section in a form array to add a set of buttons. In neither case should they be turning a link into a button by adding a CSS style attribute to some HTML markup. Never!

So... While I think having a visual guide to proper markup is a nice idea, organizing it and presenting it connected to various HTML elements and their style attributes is not the right approach.

Ideally, for module developers, the documentation should be in the RenderElement classes, such as:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Render!Element!Ta...
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Render!Element!Bu...
Those classes could/should include HIG information -- usage information for module developers -- right?

And then we can think about how to make a visual guide. We need a guide to the render elements anyway -- this is being discussed at #1617948: [policy for now] New standard for documenting form/render elements and properties -- so what I think we should be doing here is:

a) Adding information to the (now existing) RenderElement and FormElement classes for HIG for developers. Tell them how to use these render elements properly.

b) Figure out how to make a guide to render elements and have a visual browser for it. Maybe this would use KSS and maybe not, but we need to have it not tied to the HTML elements/attributes but instead to the render elements, I think?

Assuming I'm right in my previous comment about the point of this issue (as in the issue summary's "problem/motivation" section), I'm changing the title to reflect what I think is the main goal of this issue, because I think the original title is heading in the wrong direction.

So I had a thought about how we could possibly make a "living style guide" that would gently lead developers of modules in the right HIG direction:

Make a demo module within Drupal 8

Initially this module would contain several pages outlining the HIG guidelines. Each one could then be generated via a render array. This way, the "living guide" would have demo sections that are guaranteed to match our current render array output, rather than being generated by really messy horrendous HTML markup like what is currently in the patch for #2349917: Document tables.css with CSS comments, which would be really hard to keep updated. As a side effect, this guide could serve as a living reference for the render elements themselves, or at least as examples of how to use them.

If we started this demo module for HIG, we might come up with other uses too...

Thoughts? It's certainly feasible, and if we put this in Core, it would automatically be available for anyone who installed D8.

Well, I just read the issue summary, not the path that was gone through to get there -- yesterday was the first time I saw this issue, and the Problem section clearly states it is about HIG, and Bojhan, who asked me to comment here, said it was about HIG.

So... If the purpose of this issue is really about documenting the Seven theme's style guide, then go forward with KSS by all means -- but edit the top of the issue summary to take out mention of HIG, because a Seven CSS/HTML style guide is not the same as HIG documentation, and it serves a completely different purpose.

But if this issue is about making HIG documentation for module developers, then ... module developers should never be concerned about the markup and the CSS. They should be using render elements. So the HIG documentation should absolutely be tied to render elements -- it should explain how to use them properly and when to use which one, and ideally it would give them a visual display of the output.

Perhaps this needs to be two different issues?

@Lewis lets talk over IRC a bit. I am not sure if we are in complete alignment here.

I would also like to note that a HIG does not necessarily mean tight coupling with the API, if you look at many software vendors they keep those disconnected. The few software vendors that have a open and accessible hig are:

https://developer.apple.com/library/ios/documentation/userexperience/con...
https://developer.android.com/design/patterns/navigation.html

You will find that neither link or embed any API parts. The reason for this that in software development they are often considered very different types of guidelines, where a HIG/style guide is often more closely aligned with brand values and larger "principles" behind the design.

However bringing it closer together (API & UI) is I think a very smart decision. We should probably explore it a little more, because I don't like the idea of battling absolutes as to where it should live. I am more concerned about what it should look like, how we expect them to explore it and use it. Lets try and first find that common ground and avoid already talking about splitting everything, over implementation. Because I think at the end of the day we all have the same end-goal in mind - that developers create more usable and aesthetically pleasing UI's.

OK, let's step back here.

I do think we are talking about two different pieces of documentation: a "Seven Style Guide" and a "HIG Document". But let's start, for each of these, by asking the questions you'd normally ask as part of any web site strategy discussion:

a) Who the audience is (primary, secondary?).

b) What information the audience would be looking for.

c) What information you want them to get in this guide, in addition to or instead of what they think they're looking for.

d) How best to organize and present the information so that the audience can find the information they/you want/need.

And meta-question (e): Are the answers for (a) - (d) the same for these two guides?

I do not know what the answers are for the "Seven Style Guide" -- I honestly don't understand the purpose or audience -- but maybe Lewis can answer that?

I think the answers for the "HIG Document" are:

a) Audience: Module developers, primarily; also possibly theme developers if the theme has a settings page. So generally: people developing admin UI for Drupal contrib and Drupal core.

b) What they want to know: How to make their admin UI have some kind of "widget" on it (where in this context, "widget" means a particular style of button, a drag-table, a table with select radios/checkboxes in the left column, etc.), tabs across the top, etc.

c) What we want them to know: When to use and not use each "widget", and how to use them properly to end up with a usable/accessible UI (the "Guidelines" part of HIG).

d) Organization/structure: Unsure... but a visual demo of the output seems desirable, and organizing it by "widget" type (tables, buttons, etc.) seems intuitive. But... what I keep coming back to is that KSS may not be the best tool, because the information that this audience needs to end up with is something like "Make a render array with this #type or this #theme, setting these properties if your goal is this, and these other properties if your goal is that.", or "Make a modulename.links.action.yml file with this in it"... So in the end that is the information we need to give people, if our goal is "HIG Document", right?

So. What are the answers to (a) through (d) for the "Seven Style Guide"? Are these the correct answers for the "HIG Document"? And does this seem like a good way to frame the discussion?

@Lewis: For my edification, can you answer the questions in #24 for the "Seven Style Guide"?

Without jumping too far into the fray here, I have one question: Will this implementation be editable? If so, I don't see a problem with a KSS solution as a start, assuming that it's going to accompany a more robust document that lives in a central location, which is what we discussed in Amsterdam. The current implementation is simply a jumping-off point, and should be viewed as such.

RE #27... With all due respect, it's not as simple as just "Let's do this", and... this is the first I've heard of a "more robust document that lives in a central location", what's that about?

My current concerns about just deciding to go forward with this:

1. Whatever solution we adopt here for this guide or these guides, presumably we will want it displayed on api.drupal.org or some other *.drupal.org "official" web site. So we are making a technology commitment. Rather than going down a certain path because it's slick or other projects are using it, I would just like to ask that we step back and think about the questions in #24, so we can make sure that if we are asking the infra people to maintain a technology stack and Jenkins scripts and the other infrastructure that will be needed to maintain the guide as an up-to-date reference based on the latest commits to the source code, the result is really the documentation that various segments of the community need.

2. I also have concerns about some of the specific patches that are being proposed for the KSS solution, which I haven't even mentioned here but did on the specific issues. For instance, the Table documentation patch on #2349917: Document tables.css with CSS comments introduces a huge mess of HTML code into the CSS file in a comment, and I don't really think that HTML code for generating the sample will be kept updated as Drupal rendering changes; it is also very difficult to maintain and adds a lot of lines to that CSS file. So... I'm not sure that the present proposal is going to result in a guide that we can maintain current as Drupal evolves. Maybe that gets to @danigirl's concern about "will it be editable"? My answer to that, for this specific patch anyway, is no. We already have some massive documentation that people can't really edit, and it gets way out of date (the Form API reference on api.drupal.org comes to mind...). Let's not create more of that.

this is exciting, I really like the idea of a css-driven style guide / HIG.

i can see this as a great reference point for those who want to implement UI components, either for reusing existing patterns or just to demonstrate markup and class naming patterns!

what also would be interesting is to have "visual tests" for drupal UI components to generate the markup that lives in the CSS documentation tags. but this creates tight coupling to the API and is probably worth its own discussion. don't want to drive this away :)

thanks for getting this starting, looking forward to more feedback from others.

A) I think there are several audiences

1. Core developers: They have to learn about new patterns that we set.
2. Contrib developers: They have to abide by patterns that we set and learn how to make their UI more usable
3. (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.
4. Project/sales managers: They can tell their clients that the module is developed after standards, both API and UI.

B) I've already had many interviews (as you can see in the PDF). But in the past few years talked to quite a few developers who used the HIG. It seems like they need guidance on following levels:

1. High level: What kind of pages should I create, what types of listing and creation pages? (often driven by technical implementation, but not always)
2. High level: How should I allow people to navigate them? Tabs, actions, etc.
3. Detailed level: What pattern should I use (fieldset, vertical tab) and how?
4. Detailed level: How can I optimise my labels/text?

The key part being that this is incredibly concise, as UI is clearly not a main focus.

C) The end goal is what Lewis describes. The question is currently we can only really provide them the detailed view. We don't have adequate documentation for the high level decisions that developers need to make. The question is where we position "overall" documentation, we also have principles that more "generic" design principles. We don't really have a place for these in code.

D) I think this is the key question. A lot of HIG's that I have seen both publicly but mostly inside companies, have focused around a very visual way of exploring the patterns. Where the outline of this library focused from the high level concepts, to the detailed implementations (grouping by type of pattern "navigation", "grouping", "buttons", "text", "filters", etc. Often this was linked with the specific styling of that product, so brand elements (logo's, color use age, white space, etc.). I guess one of the questions we have is if we can separate styling/branding elements from the more practical guideline bits ("seven" independent).

ok, so for the Rules 8.x port we are looking for guidance on how to port/implement/improve the user interface. we haven't started worrying too much about it, because currently the focus is on developing the APIs. still, it is clear to us that it is a great challenge, so there is some discussion already documented at #2251267: Rules 8.x UI brainstorming.

in general, we are looking for high level guidance, because the Rules creators are mainly developers who can create beautiful APIs but aren't experts in UX, UI design etc.

The levels 1, 2, 3, 4 described by Bojhan in #31 already feel like a good strategy for breaking down the problem for us.

The Rules 8.x should leverage existing Drupal core UI components for listing Rules configurations etc. For the most interesting part, the Rules configuration itself, we might want to re-use concepts from ViewsInCore (add filter dialog). Actually I know that views uses those concepts but I don't have an idea what their exact names are. So just having a component library describe the things we have, would be a good starting point :)

On a related note, at DrupalCon I also attended the Search API / Facet API BoFs where we figured, that improving the Search API interface could also take an overview-layout approach as the Views configuration display does. I haven't seen us document this, but here's a link that might lead us in that direction #2250141: Have a quick look over the UI for any improvements or suggestions.

I'm happy to answer more questions on why i feel this is important, but I also have to admit that I am rather surfing on the surface than diving deep into UX myself. what i expect is something to easily grasp for both developers, designers, front-enders, PMs, etc to have a common understanding of what can be done and maybe even provide a bit of help on the process. i know that the HIG won't solve all of that, but at least to provide some context on my persona interested in it :)

OK. So it looks like in #24, #30, and #31 we have good agreement on the audience, goals, and etc., and that we are actually talking about the same guide, right? So we really do all agree that we want to build a HIG.

I've updated the issue summary to add these questions/answers... check and see if you agree how I've summarized it?

updated issue summary comment links

how about we 1) create a list of drupal 8 core module UIs and popular d7 modules which are currently ported to d8 core such as panels, rules. from there we could identify 2) common patterns like managing lists, complex add dialogs, etc for the pattern library.

OK. So... Do we have any proposal for how to present this information that would actually achieve the now-well-stated goals?

The ideas that I see above are:

a) KSS (in issue summary). So far I haven't understood how this would satisfy the current goals, but it does have the advantage of a visual presentation.

b) A demo module (comment #20), which hasn't fully been explored.

This demo module should then contain the markup that is currently in some of the css comments (from KSS), right? It should for each element provide information

• when to use the element,
• how to use the element,
• how to implement the element

It would be a new module in core, right?

And on the other hand, we have KSS-Node, which would mean we still document an example markup in the css, but we would be able to generate a styleguide using KSS node. This is would this would be that we introduce some extra tools … we would introduce node, npm and kss-node.

If my health keeps up … I might be able to start working on this.

I think this issue is too focussed on the CSS. An awful lot of the UI that, say, a Drupal contrib module will make won't be anything to do with CSS, and the contrib module in all probability won't be providing any: it'll be the choice of page hierarchy, the ordering of forms, use of messages, and so on.

Here's some examples from issues I recently filed in a contrib module:

- message when saving a form for an entity should say either 'foo has been updated' or 'foo has been created', as appropriate -- #2218189: Messages when performing operations are incorrect and inconsistent
- saving the form for a thing from a list of things (vocabulary, content type, etc) should redirect you to the list of the things -- #2332749: saving the entity type form should redirect to the entity type admin

I have thought about this a bit more...

I don't really think that a demo module is going to work out all that well as the main source for this documentation, and setting it up would be a pain (mostly because all of the text would need to be converted into PHP render arrays, which is painful at best).

I also think that KSS is probably not the right solution, for reasons outlined earlier.

Another thing we could do is to take the current drupal.org HIG and convert it into a number of @defgroup topics for api.drupal.org, and I don't think that is a terrible idea... However, that would be a LOT of topics.

So I think that the best thing to do is going to be:
a) Keep the main HIG guide on drupal.org as it is now. We'll need to update it somewhat for Drupal 8, add d7 and d8 implementation details, and make sure it is aligned right with the goals and audience stated in the issue summary.

The main problem with this is that we had this nice HIG before and no one used it or knew about it. So...:

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

c) Add links from various topics and classes in Drupal Core to relevant sections of the HIG. 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, which is still open to question on another issue, make sure that it has links to the HIG and relevant sections as well.

Personally I think this is the most viable plan, because it uses the HIG we already have (a LOT of work went into it) and rather than trying to port it to a completely new format, duplicate it, or use new technology like KSS (new to the Drupal project anyway), it uses what we already have working to increase the visibility of the existing HIG.

+1 for splitting, the two solution attempts are pretty different. i'm personally really interested in the automated seven style guide

+1 to #41, and for splitting. A style guide for Seven theme seems like a different thing from the HIG to me.

I agree.

not quite sure but just for reference http://backdrop-ops.github.io/backdrop-hig/

OK. I've split this issue up into #2404111: [Meta] Create a visual style guide for the Seven theme and #2404109: [meta] Update and improve linking to Human Interface Guidelines docs.

The Seven issue needs some work - the issue summary needs to have the section about audience, presentation, and goals filled in. I have never understood this about the Seven guide so I couldn't really fill it in. Maybe lewisnyman can do that?

Meanwhile, I'm going to close this issue as a duplicate of those two other issues, and take all the current "Add ... to CSS" issues that are children of this one and put them on the Seven guide issue instead.