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

Yes I think I may of jumped the gun on those as I was cleaning up the issue queue.

I think that was based on splitting this issues and comment #19

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)

a) I am still not sure what the purpose and audience are so it is hard to tell if this proposal would actually satisfy the goals.

We need to document the CSS components defined in the Seven theme.
So module developers can use them correctly (this is a bit like API documentation but for CSS I suppose.
And admin theme maintainers can override them correctly (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.

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

This is a lot easier now that we can separate the objectives from the HIG :)

b) Maintainability of the CSS comments in their latest iterations:
- Having the "Section 1.1" numbers hard-wired into different CSS files is not very great, because if someone wants to add a section, all the other numbers after it would need to be changed, so one localized change has large repurcussions. Can that be avoided?

The Section numbers are there to serve a purpose, they provide structure and order. We could remove them but if we did then the the components would be displayed flatly and alphabetically. Not a terrible thing but no desirable either. I've only ever seen other style guide solutions manage the structure and order in a similar way. Pattern Lab suggests leaving gaps between numbers to make it easier to insert new components when they get defined. Maybe we can look into support this in KSS but as most the components are already defined, I don't consider this to be a common use case. I can't imagine us adding components often, but it will happen every now and then.

- Having large amounts of HTML markup that we would never want developers to write directly, and in CSS file comments, also seems undesirable and not very maintainable.

This is not ideal and the maintainer of KSS has stated that this is a temporary workaround.

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.

The current state is not ideal but I think it's acceptable as temporary solution, considering it hits all the other requirements above and is more maintainable then the HTML and CSS sitting in a separate repo or website. Also, this documentation is expected to be maintained by frontend developers, who have no problem writing and editing mark up.

c) Display/location: I am not sure we've figured out a viable plan for getting this displayed on a *.drupal.org site. I'm not saying it can't be, but I'm not yet sure it can. This issue doesn't seem to have many details about what would need to be done to get it displayed.

One of the benefits of storing the content in the core repo, is that we don't need to decide where the content will be displayed now, we can work on the display solution after Drupal 8 is out. The style guide would need to pull in CSS files from core and using custom markup, and a custom design to accommodate the style guide. I'm concerned about the velocity of development on api.drupal.org, but this approach means it would be quick and simple to host it elsewhere temporarily or on design.drupal.org if it is more appropriate in the future. In fact we developer a proof of concept at Amsterdam - http://lewisnyman.co.uk/drupal-ui-guidelines/

I'm generally not in favor of adding this to the Core source if the guide can't be updated regularly

It can be updated in the same way the current api documentation can be updated, are there any problems with the way the api documentation is maintained and updated at the moment that I'm not aware of? This solution is more maintained than storing the documentation on another site, separate to the code it references.

I will move some of this into the issue summary pending a reply from you

Module developers should *not* be writing HTML markup or using the CSS classes in Seven, or relying on them. They should be using render arrays with the right #type or #theme, which will put the right HTML markup and classes on the output

Module developers do write HTML and CSS right now. You only have to look back to the issue we just committed: #2337317: Replace help page layout CSS with reuseable layout classes

There is not an equivalent #theme or #type function for every possible CSS component or class, nor should there be. That is a painful level of abstraction and there is a reason why there #attributes array exists in render arrays.

so that any theme can override the templates used for rendering and make their own CSS match their own output. Right?

Actually no, not in the case of the admin interface. It's impossible for Seven to override the output of a contrib theme. It's also a passive pain for contrib admin themes to override every module that exists ever. So the only way to keep the admin UI consistent and DRY is for Seven to lead modules, not the other way around. This is consistent with the Drupal 8 CSS standards, where all CSS are reusable design components, not module specific.

I added an issue to apidrupalorg. #2447835: Add KSS style guide for design components used in Seven theme

+1 for @lewis's point.

Front-end comment format could be different from PHP/backend comment format if needed. People who are not coming from php/drupal background, will not find this new format different or non-standard.

This makes it hard to scroll through the file and see what is comments and what is CSS

I think, IDEs do great job in differentiating color for code and comments, so this should not be that big concern.

Yeah, there is going to be some difference in previous comment style, but I think benefit of style guide is much more.

So, +1 for KSS style-guide.

the next step would be to write up a standard for these comments -- what would be added to the coding standards guide -- to formalize the exception. The step after that would be to file an issue in the Technical Working Group issue queue to request that this standard be accepted. Then once it's accepted, it would be appropriate to go back to working on patches. Meanwhile, those child issues had been postponed. They were recently un-postponed but they need to be postponed again.

Great, looks like we have a straightforward process to move forward. I was thinking we could use #2349913: Document elements.css with CSS comments as a test to see how it goes, but it looks like it's much better to do it here for visibility.

I am also opposed to adopting KSS as our standard way to make style guidelines until it is clarified exactly what we'd need to do on *.drupal.org to display the resulting style guides. I requested this on both the other issue and #11.

I disagree because the hasn't been a consensus on whether api.drupal.org is the best place to publish these guidelines. I would prefer if the documentation standards weren't influenced by the limitations for api.d.o, only because of the benefits of choosing a widely adopted, open standards.

I will postpone the other issues and move the patch over to here so we can test it and improve it.

Here is the patch from #2349913: Document elements.css with CSS comments and a screenshot of how the headings element is rendered by kss-node:

One of the criticisms is that is is different to our current multiline comment style.

This is what the same comment would look like in Doxygen style:

/**
 * Headings
 *
 * Reusable heading classes are included to help modules control the styling of
 * elements on a page without affecting accessibility.
 *
 * Markup: <h1>Heading 1</h1>
 * <h2>Heading 2</h2>
 * <h3>Heading 3</h3>
 * <h4>Heading 4</h4>
 * <h5>Heading 5</h5>
 * <h6>Heading 6</h6>
 * <h2 class="heading-c">A heading 2 styled as a heading 3</h2>
 *
 * Styleguide 1.1.4
 */

With this code, the KSS parser fails to parse this comment block at all, I'm not sure why yet, maybe JohnAlbin can help.

One of the other criticisms is that a lack of indentation makes it difficult to tell where documentation ends and code begins.

/**
  Headings

  Reusable heading classes are included to help modules control the styling of
  elements on a page without affecting accessibility.

  Markup: <h1>Heading 1</h1>
  <h2>Heading 2</h2>
  <h3>Heading 3</h3>
  <h4>Heading 4</h4>
  <h5>Heading 5</h5>
  <h6>Heading 6</h6>
  <h2 class="heading-c">A heading 2 styled as a heading 3</h2>

Styleguide 1.1.4
 */

This seems to parse, but as soon as I indent the Styleguide 1.1.4 section then it seems to break the parser.

The only errors this gives is the extra * by the title, as it's parsing the additional * at the beginning of the comment. It also seems to be printing the header again as a paragraph, maybe that's a parser error?

hurra for going with kss-node its commonly known by the frontend world and / or have known maintainer(s) (maintainer is john albin)

The styleguide could be packed with the theme ? - or would that be a huge pita to maintain. Else a new styleguide should be generated at every release, but should be tested on each patch as well (just like all the other fun test) or how do we do that, do we just make sure the syntax is correct ?

BTW We do need style guides for bartik, seven & well also classy ... ooh my ;)

Patch re-rolled. I had some conflicts.
One thing i removed was

code
pre,
kbd {
  font-size: 1.231em;
}

Also i used KSS module for enable styleguide here, and there was not option to display active admin theme https://www.drupal.org/node/2627484
I had to enable seven as default site theme. In this case was OK.
Also this patch is for 8.0.x Looks like should be done for 8.1.x ?

kss-node 3.0.0-beta3 is out and it includes a Twig.js style guide builder and a --extend-drupal8 option that adds dummy/pass-through filters, functions, tags that match the names of Drupal 8's custom Twig extensions.