Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
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.
Comments
Comment #1
cosmicdreams CreditAttribution: cosmicdreams commentedOne 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)
Comment #1.0
LewisNyman CreditAttribution: LewisNyman commentedAdded more examples
Comment #1.1
LewisNyman CreditAttribution: LewisNyman commentedUpdated issue summary.
Comment #2
LewisNyman CreditAttribution: LewisNyman commentedI'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.
Comment #3
LewisNyman CreditAttribution: LewisNyman commentedComment #4
cosmicdreams CreditAttribution: cosmicdreams commentedYou can add "holograph to that list:
https://github.com/sumpygump/holograph
(written by a colleague of mine)
Holograph is hologram ported for PHP.
Comment #5
LewisNyman CreditAttribution: LewisNyman commentedComment #6
LewisNyman CreditAttribution: LewisNyman commentedComment #7
LewisNyman CreditAttribution: LewisNyman commentedComment #8
LewisNyman CreditAttribution: LewisNyman commentedLooks 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 :-)
Comment #9
LewisNyman CreditAttribution: LewisNyman commentedComment #10
LewisNyman CreditAttribution: LewisNyman commentedSeven 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.
Comment #11
sqndr CreditAttribution: sqndr commentedI 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? ;)
Comment #12
Bojhan CreditAttribution: Bojhan commentedThis 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
Comment #13
LewisNyman CreditAttribution: LewisNyman commented