Problem/Motivation

One of the aims of the Seven style guide is to provide useful guidelines for core and contrib developers so they can make informed decisions on their UI's.

Requirements

The Seven style guide must:

  • Be quick and easy to find useful UI components.
  • Document when to use each component.
  • Reference documentation on how to use each component.
  • Provide examples of each components.
  • Provide examples of components in use together.
  • Be screen width agnostic, it should be easy to view examples in different contexts.

Inspiration

Existing solutions

Comments

cosmicdreams’s picture

cosmicdreams commented

One solution that I've seen FrontEnd Developers (FEDs) use is Hologram
http://trulia.github.io/hologram/

It allows you to document code like we have for our docblocks in a way that produces a visual style guide for pages and components. I wish I could show you screenshots of how developers are using it for the project I'm on right now. It looks pretty awesome.

The FEDs say it works well with Grunt to produce both the style guide and the compiled css (which does not include all the extra comments)

lewisnyman’s picture

lewisnyman
he/him
commented
Issue summary: View changes

Added more examples

lewisnyman’s picture

lewisnyman
he/him
commented
Issue summary: View changes

Updated issue summary.

lewisnyman’s picture

lewisnyman
he/him
commented

I'm warming to the idea of keeping all of our documentation in our CSS files in the style of Hologram/KSS. It matches how the rest of Drupal is documented and it's not specific to any particular display method. Any site or program with access to the source code would be able to parse the documentation.

lewisnyman’s picture

lewisnyman
he/him
commented
Issue summary: View changes
cosmicdreams’s picture

cosmicdreams commented

You can add "holograph to that list:
https://github.com/sumpygump/holograph

(written by a colleague of mine)

Holograph is hologram ported for PHP.

lewisnyman’s picture

lewisnyman
he/him
commented
Issue summary: View changes
lewisnyman’s picture

lewisnyman
he/him
commented
Issue summary: View changes
lewisnyman’s picture

lewisnyman
he/him
commented
Issue summary: View changes
lewisnyman’s picture

lewisnyman
he/him
commented

Looks like there's also a KSS parser for PHP.

I'm not sure which one looks better but interestingly there's a bundle that integrated with Twig :-)

lewisnyman’s picture

lewisnyman
he/him
commented
Issue tags: +styleguide, +CSS, +frontend
lewisnyman’s picture

lewisnyman
he/him
commented

Seven documentation needs to start implementation now... I've picked a direction to go with here: #2293627: [meta] Document Human Interface Guidelines and make Seven style guide

I'll leave this issue open for now incase any more discussion comes up.

sqndr’s picture

sqndr commented

I like good documentation and think it's really important. Going to take a look at #2293627 as well. Let's do this!

Really like this way of documenting: http://warpspire.com/posts/kss/.

Haha, feel like we have to document how we're going to be documenting the css? ;)

Bojhan’s picture

Bojhan commented
Status: Active » Fixed

This has been discussed by Lewis and Bojhan at the Amsterdam sprint. It looks like we are moving forward with the CSS documentation standard, therefor closing this issue. To centralise further discussion.

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

lewisnyman’s picture

lewisnyman
he/him
commented
Issue summary: View changes

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.