Style Guide: Static vs. Generation

[addyosmani]

It's time to decide whether we want Google WSK to stick with a static style guide or opt for the style guide to be auto-generated.

There are an abundance of tools for the latter, but open questions around how well they're supported, how they work with BEM/SUIT/inuit and what the current recommendations from CSS thought leaders are.

Static

The current style guide is composed of a static HTML file that pulls in styles from a Sass-based directory of components. Our Material Design version is quite similar, but uses iFrames to pull in component demos. There are pros and cons to this approach:

Pros:

• Super simple for beginners to edit/update the file to change components, visual look and feel
• Supports LiveReload, working with a preprocessor / the other nice build process bits you get with WSK

Cons:

• As it has to be manually updated, it may either become a burden to project authors or be deprioritized as it isn't part of the main site
• It's a standalone representation of style and components without a direct link to the codebase.
• The current setup requires additional build step configuration in our Gulpfile, though, this would likely be similar for any alternative approach.

  Auto-generation

The auto-generation route is advocated by projects like KSS - used by GitHub for their styleguide sample, StyleDocco and PatternLab. Team Sass has previously looked at using Yeoman generators like this one to aid in the automation process.

Pros:

• Autogenerate Style Guides when changes are made to the codebase so in theory they shouldn't be able to fall behind
• As the Style Guide is generated from source, beginners shouldn't need to manually update the end product - just adhere to the style of template necessary for auto-generation to work.

Cons:

• Gets tricky when you're working with components requiring JavaScript (where does the demo information live? Assume the generated content will be correct and include a script.js in your styleguide template?).
• Duplication of template information (you end up with demo templates in both your source comments and style guide for components that are non-trivial or a mix of multiple components)

  Requirements

Here is to the best of my understanding what we may want:

• Automated style guide generation
• Little overhead of learning yet another architecture methodology that will scare off beginners and intermediate devs.
  • E.g if we recommend BEM, SUIT or inuit for the general CSS architecture, we want to avoid (if possible) introducing yet another methodology unless it brings value. For example, I love PatternLab, but have this concern with Atomic Design, but less so KSS. Is KSS as complex? Is there something better?
• Something that works well with components that may optionally require JavaScript.
  • e.g I have a button with a ripple effect powered by JS - the solution has a way for my auto-generated guide to demo it. Is this flawed thinking or does an existing solution support it?
• A solution with up to date tooling.
  • We have no problem writing new Node modules to work with a solution if needed, but ideally the solution should have existing Node tooling around it. We can write the Gulp tasks needed if they aren't done.
  • Solution can't require users to use say, PHP. We're trying to minimize our dependency tree as much as possible.

    Open questions

• Do Team Sass have a preferred setup for style guide generation? @jina talked about this at CSSConf
• Is KSS actively maintained? The commit frequently seems to have slowed down in the last 6 months https://github.com/kneath/kss/commits/master
• Does SUIT or inuitcss have a preferred solution for style guide generation that works well with those architectures? (cc @necolas @csswizardry)
• How do existing techniques solutions with newer CSS architectures? e.g let's say I want to use SUIT as part of my architecture. Do I have to make the decision to use the architecture outlined by PatternLab / KSS/ StyleDocco over it. Does it generally not make sense to deviate from recommended structure?

[addyosmani]

Adding a few folks for their thoughts (sorry for the noise and feel free to ignore me!) :)

Team Sass: @jina @nex3 KSS: @kneath @benschwarz

[necolas]

I don't think any of the listed generation options are good. I'd suggest rendering full components in a styleguide (which becomes just another app) and not using any CSS comment stuff. Harder for you at this point in time though.

[jina]

Just a clarification… Team Sass (who made the North style guide generator, with @snugug & @scottkellum, etc.) is different from Team Sass Design — the former makes tools to use with Sass, the latter, which I lead, is the team that designs the site & other things for Sass. :)

If I'm not mistaken, I believe they're gonna rename themselves at some point to avoid further confusion.

Since I tagged them here, maybe they can give their POV. :)

[jina]

@necolas I am very curious why CSS commenting for style guide generation is something you don't recommend? :)

[dmolsen]

For clarification, the PHP version of Pattern Lab is meant to be an empty container that basically only gathers dynamic data and compiles mark-up. Anything else is fair game. This includes nuking the atomic design organization, using a CSS pre-processor or whatever CSS framework you want. It's very un-opinionated in that respect.

I love KSS and it's just reached a point where it's stable and doesn't need big changes. It allows a designer to add their documentation where it makes sense to them and is a boon to folks who need to maintain those styles. I wouldn't embed mark-up to go along with those styles though. That appears to be unmaintainable for anything more complex than the ubiquitous button example.

[kneath]

Is KSS actively maintained? The commit frequently seems to have slowed down in the last 6 months

Yep! KSS is primarily a spec (the format of the comments), of which there isn't much that needs changing. Since it hasn't changed much, there haven't been many code changes to the ruby parser at kneath/kss. Without many code changes, there haven't been many bugs, which means there's a low commit frequency. I do still pay attention to Issues & Pull Requests though.

Also as per my opinion, I can't recommend an auto-generated styleguide enough. Get as close to production as humanly possible. Remove doubt in your testing/styleguide. In GitHub's styleguide, we even use the same Rails helpers we use to generate actual views (with mock model objects/data). The only thing worse than no styleguide is an outdated styleguide that gives you false confidence.

[scottkellum]

Your pros/cons seem accurate. I would add that static style guides allow for significantly more flexibility in presentation and as a result the components themselves can sometimes be more flexible (illustrate how they appear in different context or with modifiers and different content).

Maintainability of auto-generated style guides is pretty clutch though, hard to beat that. If what you are building is relatively straightforward, which would be ideal, then KSS or similar seems like the best bet.

@jina Leaving the name change in the hands of @snugug, but yeah, it needs to happen.

[jina]

Agree with @kneath on autogeneration. It's like I mentioned in that talk I gave where we met, Addy. :-) Style Guides must be current & useful. If they are no longer current, they are no longer useful.

I like a hybrid approach. Automated, with room to customize style guide layouts to your needs.

[Snugug]

@jina @scottkellum Yes, we need to change the name, we just can't find another one. Naming things, ya know. Anyway…

Some of my insight while building and using Style Prototypes:

• Distributing as a Yeoman generator is a huge win for Style Prototypes. It allows for easy distribution and maintenance of the core systems, and distributing the core generation tasks as a Gulp module and Bower plugin make updating to the most current versions a breeze. I've found that only adding to the user's codebase the bare minimum needed for them and having everything else be maintained behind the scenes to be a win.
• Styling for the actual user interface is done exclusively through data attributes to ensure styling choices don't clash. The styling for the UI is done in Sass and included via Bower as a generated CSS file, but users can choose to remove that file, pull in the partials used to generate it, and write their own styling (or add their own styling on top). This makes creating custom layouts fairly easy. Angular helps in this instance as well, as the user has full control over pretty much everything outside of ng-view and ng-view is more or less just the listing of components.
• While it comes bundled with (and a user can choose) either Atomic Design or North partial structure, neither are required, and no CSS naming conventions are enforced. I think this is a must in order to make it generally usable.
• We enforce CSS Preprocessing with Sass as we believe that's the best way forward (and makes it easier to maintain/reuse/cherry-pick styling), but there's no reason to. If you are, however, I'd recommend Sass and generator-sass.
• For JavaScript, we encourage building self contained (as much as possible) JS files per component that can be loaded in and used/remixed as needed.
• For demo content, we use yml that gets loaded in and is available as variables (front-end is built using Angular, so we make them available through the scope). Each section of patterns plus the page view (allowing to combine multiple components/layouts onto a page) has its own set of yml for content that can override other as needed.
• Entire automatically generated guide can be exported to static HTML.
• HTML is stored and written in HTML files, and menu structure is automatically generated based off of folder structure.

FWIW, having done a bunch of user interviews around this, I've found there are two groups of people who use Style Guide tools; those who use them primarily as documentation tools and those who use them as both design and documentation tools. Users of KSS and the like I find skew towards those who use the tools primarily for documenting their CSS (and likewise prefer HTML in their CSS comments). Users of Pattern Lab and Style Prototypes I find skew towards those who use the tools as both design and documentation tools, so I think that's something to consider.

Another consideration that we're dealing with at IBM is how we take these patterns built in our style guides and use them. For static sites, copying the HTML over is good enough, pretty much like a custom version of Bootstrap or Foundation. But for anything deeper or any further integrations, these style guides need to be treated as a baseline with implementation-specific builds; kinda like Bootstrap and UI Bootstrap. In this case, we would like to reuse (or have a conversion process) as much as possible and only rewrite what we need to (most likely the JavaScript).

[blackfalcon]

Interesting conversation in here. I'd like to add that I pretty much agree with comments by @Snugug, @necolas and @scottkellum.

Issues I have seen with building static style-guides is the amount of maintenance needed. In the beginning this seems ok, but as time goes on, no one wants to be the maintainer of the style-guide all the time.

On the other hand, automated solutions like KSS, I have never seen really win either. KSS still requires manual maintenance, and I find this very distracting, using the HTML comments method. Over time I see the CSS changing in the style-guide, but the HTML representations slowly rot over time due to lack of maintenance.

The real issue I see with living style guides is that they are viewed as 'design' tools and are not typically adopted by the engineering teems. And when there is additional work, or duplication of effort, for the sake of 'better code', 9 times out of 10 people will opt for the easier route.

In my opinion, I see the success of style guides requires that they either live within the actual application itself or the structure needs to be independently modular. Each solution has their +/- in application.

In either case, documentation of the style guide and Sass needs to be as automated as much as possible. I am a fan of exposing the actual code in a view that makes up a module, not just sudo code to 'represent' a UI model. The more real code used, the better.

A style guide that lives within the app is directly applicable, but you need to support this secondary environment for your app.

Externally required that your functional modules be independent of context, extendible, flexible and require an API for insertion to the actual application. All very achievable goals, but slightly more work. In the end I really like this approach as it ensures that you really are building a scaleable application.

Also, with advances in javascript frameworks, specifically Backbone, the external module is very achievable and very applicable to different development environments such as Rails, .NET, Java and JavaScript stack apps.

As an additional kicker, I have also been meaning to look more into the SassDoc tools for automation of the custom Sass code API, which is usually the buried resource in most style guides.

So, to summarize, a successful style guide needs to:

1. Be directly applicable to the app env without additional work to 'integrate' the UI models
2. HTML template, Sass and presentational Js is directly applicable to the app
3. Allows for abstract modular development
4. Style guide and documentation needs to be as automated as possible
5. Is used by the Design team as well as part of the App engineers workflow

[Ianfeather]

The static route is tricky one to get right in my opinion, although @Snugug's approach seems to be about as good as you could get. I wrote about some of the problems with static style guide generators here http://ianfeather.co.uk/a-maintainable-style-guide/

We built our style guide as a separate app which uses the same components as the site (similar to what @necolas suggested), though you need to have control over the full stack which doesn't feel like it would fit with the starter kit model.

[gauntface]

@Ianfeather great post.

Sounds like everyone is rolling there own thing depending on the stack they have and use for their projects, the approach is always the same - split out HTML template, css and js and have a tool to pull it all together.

In our case it would be a tool to include the HTML template and a tool to pair up the required CSS / Sass and JS into the final minified and concatenated JS and CSS.

[triblondon]

At the FT we have a component registry that auto-discovers compatible UI components. The components are all individual git repos with bower package metadata. The registry then generates a doc page for the component, along with all the demos, and we have a build-on-demand service to load the CSS and JS files into the demo iframes.

Gallery is a good example of a reasonably complex component.

We're very enthused by the idea of componentised UI, and would love to see better tooling as well as better standards like a proper module concept in CSS.

[addyosmani]

Thank you to everyone who took time out of their days to comment on the thread so far. Your insights have been immensely useful.

We're still evaluating what the best set of tooling options to use here are. That said, based on your feedback we will definitely be automatically generating the style-guide. We'll try to keep customisation of the output as easy as possible.

Some of the decisions we still have to make:

• Are markup/templates in your styles (per KSS) a maintainable solution for users long-term? This thread has brought up some interesting concerns around their sustainability. I can see the argument for pulling in markup with extra tools and we may end up doing this to avoid inline markup.
• If inline templates are not maintainable, are there off-the-shelf options for specifying external template files that work well with KSS? (or a similar methodology). What we're trying to do here is define a workflow for Style-guide driven development that the intermediate developer can use. I have yet to take a look at the slimmer version of PatternLab so it's unclear how well it may fit as an alternative.

Ultimately, the documentation for each component and its styles have to live somewhere and agree it's best this live within a component rather than in a static resource that isn't tied to living UI.

[addyosmani]

@Snugug, @jina, @kneath @necolas @scottkellum: I believe we're on the same page (or close here).

@necolas re: your full components being rendered comment. Would a demo.html file for each component containing numerous markup samples consuming styles & JS basically be what you're suggesting?

Some tool would then aggregate them as part of the style-guide generation process perhaps. I think you would still require CSS comments for additional context, unless this extra info is going directly alongside the demos.

[blackfalcon]

@addyosmani this was something that I tried to bring to life with a project a while back called Toadstool. it's all Ruby, but the idea for sure is that all the modules are independent partials and the actual code that will appear in the app, appears in the style guide.

In the end, the app and the style-guide are just presentations of the module. The idea is to be presentation agnostic. This process really plays well with concepts like "white label" projects where there needs to be a complex theme application scenario.

[benschwarz]

Are markup/templates in your styles (per KSS) a maintainable solution for users long-term? This thread has brought up some interesting concerns around their sustainability. I can see the argument for pulling in markup with extra tools and we may end up doing this to avoid inline markup.

Its fair to say that as a project, KSS is against putting HTML in the comment section:

• Kyle's commentary on PR #97
• kneath/kss#77

[necolas]

@addyosmani More that the styleguide is an app that renders each component (and each configuration of a component, if you want). Might be too much for this project, but that's how a widget gallery should be created – zero maintenance / no duplication of widget code.

[benschwarz]

Super great commentary above, you are all excellent humans. :rose:

---

I've built/been apart of a few component libraries for a number of clients over the past year or so, some used KSS, some Styledocco. (of course the tech made no difference to the result).

More recently, I've been a fan of the following approach:

Each UI component has a README.md (containing documentation, inclusive of HTML demos), a component-name.css, component-name.js and a component-name.html.

• component-name.html is rendered by the documentation/styleguide generator (if it isn't present, we simply render the README instead)
• bower.json's metadata is used to know which component files to load for the styleguide (or, we just use the naming convention).
• A usual / UI diffing test suite then runs over each component (and its variations) and ensures that they're rendering as expected in all demos described in the README — failures are caught before the "tag & release" build step.

This process is not dissimilar to some of the work that FTLabs origami have been doing (hollar @triblondon), and has worked with great success.

---

Some throw away thoughts:

KSS or other magic solutions don't aid you in creating a styleguide, they help you have rules in which to author your styles (and hey, describe what "a good comment" actually is).

The "hard part" is:

• Load the components requirements
• Show component/widget demo
• Display the code used for the above demo
• Show variations
• Show version information/changelogs/metadata
• Break down common elements like colours, typography and utilities that aren't exactly "a component"

[blackfalcon]

@benschwarz :+1:

[addyosmani]

Thanks for the detailed thoughts @benschwarz! :star:

Each UI component has a README.md (containing documentation, inclusive of HTML demos), a component-name.css, component-name.js and a component-name.html.

I like the setup you're describing. Some follow-up questions:

• You mentioned you've used KSS and Styledocco in the past, but your setup summary above doesn't appear to use either. Are you still using one of them for documenting your styles or is the complete set of docs for the component living in the README.md?
• Is your process of rendering the demo files (or READMEs) into your style guide effectively akin to a static site generator? i.e specify a number of pages & templates used to produce a final page?

[renevanderlende]

Great discussion, but as a noob to all this sass,less,node,gem,ruby and thus web-starter-kit I have enough trouble as it is to create some kind of base design for my site(s). Each new tool steepens the learning curve (and their always unanticipated bugs/hidden features). For now the static StyleGuide is my only stronghold to learn what WSK is all about.

As a pro (senoir software engineer in db-environment, 20 yrs. exp.), depending on the accuracy and consistency of the WSK and its updates, I would opt for a static StyleGuide for learning purposes and consistent versioning as the WSK will reach maturity at some point without needing much further modification.

Why don't you simply keep the WSK static/variable as it is and

• add a new folder "custom" to the main styles sass folder.
• add an @import "../custom/xxxx/xxxx.scss" at the bottom of each xxxx.scss
• put empty xxxx.scss files in the "custom" folder (just with nice copyrights, comments, etc.)

This way the WSK-team can modify WSK to their liking without having to worry about compatibility issues with newer versions, local versions of WSK stay intact (and thus consistent) and developers can add, modify, override any CSS/JS through the "custom" folder.

As I plan to do something like that locally, I'd be happy to modify my own WSK fork and issue a pull request when finished.

Let me know what you think, Cheers, Rene!

[triblondon]

@benschwarz very exciting to hear you've had success with a pattern like Origami. We should talk more.

[benschwarz]

@addyosmani Sorry for the long time in between replies; Busy times.

You mentioned you've used KSS and Styledocco in the past, but your setup summary above doesn't appear to use either. Are you still using one of them for documenting your styles or is the complete set of docs for the component living in the README.md?

TBH, I've been using them less and less.

I think convention heavy codebases that have / follow guidelines for authoring components and styles are often "enough". (Or, y'know, teams that have a style and accurately provide peer review).

Is your process of rendering the demo files (or READMEs) into your style guide effectively akin to a static site generator? i.e specify a number of pages & templates used to produce a final page?

They can be; A build process can easily export & deploy artefacts, but more often than not I think its best to have an application that "does it live" (with some caching) — What FTLabs have done with Origami is super rad, and I think the next time around I'll be sending some time to see if that can be utilised rather than coming up with something home baked for the next project that I'm involved with.

@triblondon I'd love to talk more, and I'm sorry my correspondence has been so limited. I'll try harder to stay in touch! :muscle:

[necolas]

@addyosmani Who is the intended audience for this project? Knowing that might make it easier to decide what features to include. It will be hard to appeal to, and adequately serve both "professionals" and "newcomers". An automatic component gallery is pretty heavy-duty at this time – usually for long-lived apps with multiple designers and engineers. I'd not bother TBH.

[RiZKiT]

I expect this is way over the top for wsk, but maybe someone is interested in the concept of Lonely Planet's approach. Blog article: A Maintainable Style Guide Live styleguide: http://rizzo.lonelyplanet.com/styleguide

[robhrt7]

Hi,

Thanks to all for really interesting discussion here, and special thanks to Web Starter Kit founders, for including Style Guide template by default. I really believe this will help pushing documentation first approach to wide spectre of developers.

Recently I was doing a full depth overview of current Living Style Guide tools (slides here), and we're also developing own Living Style Guide Platform called SourceJS. Knowing the differences between current tools, and understanding the role of Web Starter Kit, I would recommend some simple Style Guide generator (static site builder), focused on well structured web components.

Among all the tools, that I overviewed, I would recommend using Fabricator by @LukeAskew (or similar) in Starter Kit. It's simple, and quite extendable, plus it contains Gulp build processes for build watch and etc.

Fabricator is parsing components folder with pre-defined structure, and generates static site in few pages. On input it collects .html and .md files, named the same as described component.

Yet, it will still need some improvements:

• Components folder organisation, where each component need to have its own folder with all technologies (.md, .css, .html, .js) no only .md and .html file
• It should be extendable in terms of choosing the templating engine. Since HTML snippets must be not copy pasted from real application sources, and must use same temples.

Comparing with other tools I want to emphasise that CSS parsing way is very limited, and will suit only basic components documentation. WSK also must not promote the copy/paste approach, that you eventually will have, leaving markup example in CSS comments.

But if you still want to consider choosing CSS Documentation parsers, I recommend using DSS as the best, modular solution.

Pattern Lab is too opinionated and design focused and our SourceJS despite the fact that it's modular and easy extendible, is still to complex for most use cases.

Hope this will help. And btw, I'll be always happy to collaborate on Style Guide tooling projects, just drop a line @operatino.

[LukeAskew]

Thanks for the shout-out @operatino. Fabricator has just been a pet project of mine so it's good to see someone else finding it useful.

I think @benschwarz's points are very valid. Those are some of the issues I tried to address with Fabricator, albeit with a slightly different approach (looking for suggestions!).

I wrote Fabricator because I didn't like how the other projects approached problem at the time. Here's some of the things I was hoping to achieve:

• Focused on the toolkit/pattern library/framework/ as the output; templates/pages are tangential.
• Unopinionated - allow devs to define their own architecture and taxonomies.
• Unobstrusive - come out of the box with very little styling.
• Make documentation as frictionless as possible - derive most from the code.
• Have a single source of truth for each component - don't write the same markup for a component in two or more places.
• Output a static site (don't require database or back-end language)
• Output back-end-agnostic code examples.

Fabricator certainly doesn't get a lot of these right, but I'm hoping to make improvements! :cocktail:

[alejandroiglesias]

Hey, this is a very interesting talk. I've been considering some of these tools and doing some work with KSS. Still not 100% happy since I've been putting efforts in customizing the template and still would like some customizations that are outside the short-term scope of KSS (AFAIK) as well as the project I'm working on, namely: toggling markup example displaying, being able to use different markups for showing the example and for showing the markup itself (want to add sample text for displaying the component, but display just "..." inside of the example markup, like in Bootstrap styleguide), as well as defining pages in a more sane way, like having a simple config file in which you define the pages/sections structure and use that to build a custom navigation. Other solutions seem to add some of those features at some cost, being it a stronger opinion, more complex workflow for starting with it, or different mindset that differs from mine and my goals currently. I'm sad that I don't have time currently to make a fork of kss-node and work on those features. Will see in the future.

@addyosmani are you still thinking about all this? Do you have stronger opinions now or are you biased towards a specific tool/workflow? Do you have thoughts on how to integrate JS components into the generated styleguide?

Thanks.

[gauntface]

🐛 Bankruptcy: Closing due to inactivity.

[alejandroiglesias]

Have you considered by any chance a component explorer like Storybook? It also supports React and Angular components. Do any folks have experience with that approach?