[Meta] Create a visual style guide for the Seven theme

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 Seven Style Guide. See #2404109: [meta] Update and improve linking to Human Interface Guidelines docs → for the HIG.

Audience goals

Module developers, who seek to understand how to build an admin interface for their module that is consistent with the existing admin interface.

Contrib admin theme maintainers, who seek to understand which UI components they need to support and override in order to support core and contrib Drupal modules. (See: Changes to Drupal 8 that affect admin theme maintainers)

Previous attempts at documenting the Seven Style Guide and their pitfalls

Proposal: A Style Guide for Seven — Static images and text maintained on g.d.o. Does not evolve alongside development in core, quickly became out of date with the evolving style guide. Content is managed elsewhere, so it's easy to forget to update it. Static images are not a great way to display designs, due to lack of browser and viewport context.

Seventy eight sandbox — Documented components in HTML + CSS, built on a style guide framework that allows you to view the components at different viewport sizes and browsers. Also out of date with core, as the content and styling is managed elsewhere.

We also had a design test module in Drupal 8 that was unused #2037569: Remove design_test module →

Current proposal requirements based on previous efforts

• Must stay up to date the evolution of the implementation in core
• Must display how the context of the browser and viewport affect the display of components
• Must be difficult to "forget" to update the style guide content when required

Proposed resolution

Build a guide using KSS

We explored some possible solutions in #2102191: Discuss the availiable solutions to document the Seven style guide → . We propose the following:

1. Use inline CSS comments

• They mimic the same placement as Drupal's PHP functions.
• The are tied directly to the code, so if the CSS is updated it's easy to update the documentation if need be
• They are not tied to a specific display, which means any site that checks out the D8 repo can parse the comments and generate documentation. This allows us to find the best solution for the documentation display over time without modifying the core repo. We could expand api.drupal.org or create a new site like #2235485: [meta] Automated Theme Component Library - Overall concept/discussion → or use a completely separate site
• It follows a similar approach to api.drupal.org, using comments in code

2. Use a CSS document syntax parser
We propose following the same modal as for API.Drupal.org by having a document syntax parser. We will follow the relevant guidelines that are set in API documentation and comment standards → . However we will need to append these guidelines with some specific style guide tags to allow for appropriate styling in the website.

3. Provide a website that provides the pattern library
We propose using the KSS document syntax parser. This provides us with the HTML structure to build a website, following common user interface library patterns of grouping similar patterns. This means that the pattern library will be auto-generated and auto-updated following the information architecture and styling that we wish. Without having to hinder other parts of our documentation.

KSS attempts to provide a methodology for writing maintainable, documented CSS within a team. Specifically, KSS is a documentation specification and styleguide format. It is not a preprocessor, CSS framework, naming convention, or specificity guideline.

The full specification of KSS can be read at Spec on GitHub. The KSS framework is used by several other organisations and has a Node.JS or PHP implementation.

Remaining tasks

2. #2321505: Split Seven's style.css into SMACSS categories →
3. Add CSS documentation to each one:
   1. Layout - #2349897: Document layout.css with CSS comments →
   2. Icons
   3. Typography - 📌 Document elements.css with CSS comments Postponed
      1. Headers
      2. Paragraphs
   4. Tables - 📌 Document tables.css with CSS comments Postponed
   5. Form Inputs - #2349919: Document form.css with CSS comments →
   6. Buttons - 📌 Document buttons.css with CSS comments Postponed
   7. Dropbuttons - #2349921: Document dropbutton.component.css with CSS comments →
   8. Tabs - #2349947: Document tabs.css with CSS comments →
      1. Primary tabs
      2. Secondary tabs
      3. Vertical tabs
   9. Breadcrumbs - #2349953: Document breadcrumb.css with CSS comments →
   10. Pagination - #2349959: Document pager.css with CSS comments →
   11. Content header
   12. Modal dialog - #2349927: Document dialog.theme.css with CSS comments →

Beta phase evaluation

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

Follow up improvements

1. Provide the documentation closer to the methods.
2. Provide references to the relevant templates, to allow direct linking.

User interface changes

None.

API changes

None.