davidbgk
/
larlet-fr-david-cache

<!doctype html><!-- This is a valid HTML5 document. -->
<!-- Screen readers, SEO, extensions and so on. -->
<html lang=fr>
<!-- Has to be within the first 1024 bytes, hence before the <title>
  See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset -->
<meta charset=utf-8>
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 -->
<!-- The viewport meta is quite crowded and we are responsible for that.
  See: https://codepen.io/tigt/post/meta-viewport-for-2015 -->
<meta name=viewport content="width=device-width,minimum-scale=1,initial-scale=1,shrink-to-fit=no">
<!-- Required to make a valid HTML5 document. -->
<title>Living Style Guide Tools In-depth Overview (archive) — David Larlet</title>
<!-- Generated from https://realfavicongenerator.net/ such a mess. -->
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons/favicon-16x16.png">
<link rel="manifest" href="/manifest.json">
<link rel="mask-icon" href="/static/david/icons/safari-pinned-tab.svg" color="#5bbad5">
<link rel="shortcut icon" href="/static/david/icons/favicon.ico">
<meta name="apple-mobile-web-app-title" content="David Larlet">
<meta name="application-name" content="David Larlet">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="msapplication-config" content="/static/david/icons/browserconfig.xml">
<meta name="theme-color" content="#f0f0ea">
<!-- That good ol' feed, subscribe :p. -->
<link rel=alternate type="application/atom+xml" title=Feed href="/david/log/">

  <meta name="robots" content="noindex, nofollow">
  <meta content="origin-when-cross-origin" name="referrer">
  <!-- Canonical URL for SEO purposes -->
  <link rel="canonical" href="https://medium.com/@operatino/living-style-guide-tools-in-depth-overview-28cfffb92d05">

<style>
/* http://meyerweb.com/eric/tools/css/reset/ */
html, body, div, span,
h1, h2, h3, h4, h5, h6, p, blockquote, pre,
a, abbr, address, big, cite, code,
del, dfn, em, img, ins,
small, strike, strong, tt, var,
dl, dt, dd, ol, ul, li,
fieldset, form, label, legend,
table, caption, tbody, tfoot, thead, tr, th, td,
article, aside, canvas, details, embed,
figure, figcaption, footer, header, hgroup,
menu, nav, output, ruby, section, summary,
time, mark, audio, video {
  margin: 0;
  padding: 0;
  border: 0;
  font-size: 100%;
  font: inherit;
  vertical-align: baseline;
}
/* HTML5 display-role reset for older browsers */
article, aside, details, figcaption, figure,
footer, header, hgroup, menu, nav, section { display: block; }
body { line-height: 1; }
blockquote, q { quotes: none; }
blockquote:before, blockquote:after,
q:before, q:after {
  content: '';
  content: none;
}
table {
  border-collapse: collapse;
  border-spacing: 0;
}

/* http://practicaltypography.com/equity.html */
/* https://calendar.perfplanet.com/2016/no-font-face-bulletproof-syntax/ */
/* https://www.filamentgroup.com/lab/js-web-fonts.html */
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Regular-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Regular-webfont.woff') format('woff');
  font-weight: 300;
  font-style: normal;
  font-display: swap;
}
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Italic-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Italic-webfont.woff') format('woff');
  font-weight: 300;
  font-style: italic;
  font-display: swap;
}
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Bold-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Bold-webfont.woff') format('woff');
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: 'ConcourseT3';
  src: url('/static/david/css/fonts/concourse_t3_regular-webfont-20190806.woff2') format('woff2'),
       url('/static/david/css/fonts/concourse_t3_regular-webfont-20190806.woff') format('woff');
  font-weight: 300;
  font-style: normal;
  font-display: swap;
}


/* http://practice.typekit.com/lesson/caring-about-opentype-features/ */
body {
  /* http://www.cssfontstack.com/ Palatino 99% Win 86% Mac */
  font-family: "EquityTextB", Palatino, serif;
  background-color: #f0f0ea;
  color: #07486c;
  font-kerning: normal;
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: subpixel-antialiased;
  text-rendering: optimizeLegibility;
  font-variant-ligatures: common-ligatures contextual;
  font-feature-settings: "kern", "liga", "clig", "calt";
}
pre, code, kbd, samp, var, tt {
  font-family: 'TriplicateT4c', monospace;
}
em {
  font-style: italic;
  color: #323a45;
}
strong {
  font-weight: bold;
  color: black;
}
nav {
  background-color: #323a45;
  color: #f0f0ea;
  display: flex;
  justify-content: space-around;
  padding: 1rem .5rem;
}
  nav:last-child {
    border-bottom: 1vh solid #2d7474;
  }
  nav a {
    color: #f0f0ea;
  }
  nav abbr {
    border-bottom: 1px dotted white;
  }

h1 {
  border-top: 1vh solid #2d7474;
  border-bottom: .2vh dotted #2d7474;
  background-color: #e3e1e1;
  color: #323a45;
  text-align: center;
  padding: 5rem 0 4rem 0;
  width: 100%;
  font-family: 'ConcourseT3';
  display: flex;
  flex-direction: column;
}
  h1.single {
    padding-bottom: 10rem;
  }
  h1 span {
    position: absolute;
    top: 1vh;
    left: 20%;
    line-height: 0;
  }
    h1 span a {
      line-height: 1.7;
      padding: 1rem 1.2rem .6rem 1.2rem;
      border-radius: 0 0 6% 6%;
      background: #2d7474;
      font-size: 1.3rem;
      color: white;
      text-decoration: none;
    }
h2 {
  margin: 4rem 0 1rem;
  border-top: .2vh solid #2d7474;
  padding-top: 1vh;
}
h3 {
  text-align: center;
  margin: 3rem 0 .75em;
}
hr {
  height: .4rem;
  width: .4rem;
  border-radius: .4rem;
  background: #07486c;
  margin: 2.5rem auto;
}
time {
  display: bloc;
  margin-left: 0 !important;
}
ul, ol {
  margin: 2rem;
}
ul {
  list-style-type: square;
}
a {
  text-decoration-skip-ink: auto;
  text-decoration-thickness: 0.05em;
  text-underline-offset: 0.09em;
}
article {
  max-width: 50rem;
  display: flex;
  flex-direction: column;
  margin: 2rem auto;
}
  article.single {
    border-top: .2vh dotted #2d7474;
    margin: -6rem auto 1rem auto;
    background: #f0f0ea;
    padding: 2rem;
  }
  article p:last-child {
    margin-bottom: 1rem;
  }
p {
  padding: 0 .5rem;
  margin-left: 3rem;
}
  p + p,
  figure + p {
    margin-top: 2rem;
  }

blockquote {
  background-color: #e3e1e1;
  border-left: .5vw solid #2d7474;
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 1rem;
  margin: 1.5rem;
}
  blockquote cite {
    font-style: italic;
  }
  blockquote p {
    margin-left: 0;
  }

figure {
  border-top: .2vh solid #2d7474;
  background-color: #e3e1e1;
  text-align: center;
  padding: 1.5rem 0;
  margin: 1rem 0 0;
  font-size: 1.5rem;
  width: 100%;
}
  figure img {
    max-width: 250px;
    max-height: 250px;
    border: .5vw solid #323a45;
    padding: 1px;
  }
figcaption {
  padding: 1rem;
  line-height: 1.4;
}
aside {
  display: flex;
  flex-direction: column;
  background-color: #e3e1e1;
  padding: 1rem 0;
  border-bottom: .2vh solid #07486c;
}
  aside p {
    max-width: 50rem;
    margin: 0 auto;
  }

/* https://fvsch.com/code/css-locks/ */
p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
  font-size: 1rem;
  line-height: calc( 1.5em + 0.2 * 1rem );
}
h1 {
  font-size: 1.9rem;
  line-height: calc( 1.2em + 0.2 * 1rem );
}
h2 {
  font-size: 1.6rem;
  line-height: calc( 1.3em + 0.2 * 1rem );
}
h3 {
  font-size: 1.35rem;
  line-height: calc( 1.4em + 0.2 * 1rem );
}
@media (min-width: 20em) {
  /* The (100vw - 20rem) / (50 - 20) part
     resolves to 0-1rem, depending on the
     viewport width (between 20em and 50em). */
  p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
    font-size: calc( 1rem + .6 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.5em + 0.2 * (100vw - 50rem) / (20 - 50) );
    margin-left: 0;
  }
  h1 {
    font-size: calc( 1.9rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.2em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
  h2 {
    font-size: calc( 1.5rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.3em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
  h3 {
    font-size: calc( 1.35rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.4em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
}
@media (min-width: 50em) {
  /* The right part of the addition *must* be a
     rem value. In this example we *could* change
     the whole declaration to font-size:2.5rem,
     but if our baseline value was not expressed
     in rem we would have to use calc. */
  p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
    font-size: calc( 1rem + .6 * 1rem );
    line-height: 1.5em;
  }
  p, li, pre, details {
    margin-left: 3rem;
  }
  h1 {
    font-size: calc( 1.9rem + 1.5 * 1rem );
    line-height: 1.2em;
  }
  h2 {
    font-size: calc( 1.5rem + 1.5 * 1rem );
    line-height: 1.3em;
  }
  h3 {
    font-size: calc( 1.35rem + 1.5 * 1rem );
    line-height: 1.4em;
  }
  figure img {
    max-width: 500px;
    max-height: 500px;
  }
}

figure.unsquared {
  margin-bottom: 1.5rem;
}
  figure.unsquared img {
    height: inherit;
  }


@media print {
  body { font-size: 100%; }
  a:after { content: " (" attr(href) ")"; }
  a, a:link, a:visited, a:after {
    text-decoration: underline;
    text-shadow: none !important;
    background-image: none !important;
    background: white;
    color: black;
  }
  abbr[title] { border-bottom: 0; }
  abbr[title]:after { content: " (" attr(title) ")"; }
  img { page-break-inside: avoid; }
  @page { margin: 2cm .5cm; }
  h1, h2, h3 { page-break-after: avoid; }
  p3 { orphans: 3; widows: 3; }
  img {
    max-width: 250px !important;
    max-height: 250px !important;
  }
  nav, aside { display: none; }
}

ul.with_columns {
  column-count: 1;
}
@media (min-width: 20em) {
  ul.with_columns {
    column-count: 2;
  }
}
@media (min-width: 50em) {
  ul.with_columns {
    column-count: 3;
  }
}
ul.with_two_columns {
  column-count: 1;
}
@media (min-width: 20em) {
  ul.with_two_columns {
    column-count: 1;
  }
}
@media (min-width: 50em) {
  ul.with_two_columns {
    column-count: 2;
  }
}

.gallery {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-around;
}
  .gallery figure img {
    margin-left: 1rem;
    margin-right: 1rem;
  }
  .gallery figure figcaption {
    font-family: 'ConcourseT3'
  }

footer {
  font-family: 'ConcourseT3';
  display: flex;
  flex-direction: column;
  border-top: 3px solid white;
  padding: 4rem 0;
  background-color: #07486c;
  color: white;
}
  footer > * {
    max-width: 50rem;
    margin: 0 auto;
  }
  footer a {
    color: #f1c40f;
  }
  footer .avatar {
    width: 200px;
    height: 200px;
    border-radius: 50%;
    float: left;
    -webkit-shape-outside: circle();
    shape-outside: circle();
    margin-right: 2rem;
    padding: 2px 5px 5px 2px;
    background: white;
    border-left: 1px solid #f1c40f;
    border-top: 1px solid #f1c40f;
    border-right: 5px solid #f1c40f;
    border-bottom: 5px solid #f1c40f;
  }
</style>

<h1>
  <span><a id="jumper" href="#jumpto" title="Un peu perdu ?">?</a></span>
  Living Style Guide Tools In-depth Overview (archive)
  <time>Pour la pérennité des contenus liés. Non-indexé, retrait sur simple email.</time>
</h1>
<section>
  <article>
    <h3><a href="https://medium.com/@operatino/living-style-guide-tools-in-depth-overview-28cfffb92d05">Source originale du contenu</a></h3>
    <h3 name="dfd5" id="dfd5" class="graf--h3">Intro</h3>

<p name="f09c" id="f09c" class="graf--p">This overview is the outcome of a research on the current open source solutions followed by my personal feedback.</p>

<p name="a528" id="a528" class="graf--p">Arranging the tools by functional aspects, I will highlight only the most powerful ones worth knowing. You can find more tools as well as videos, articles and other materials about Style Guides at <a href="http://styleguides.io/tools.html" data-href="http://styleguides.io/tools.html" class="markup--anchor markup--p-anchor" rel="nofollow">styleguide.io</a>.</p>

<p name="a05d" id="a05d" class="graf--p">Before we start, if you are not yet familiar with Living Style Guides topic, I would suggest looking into these materials:</p>

<blockquote name="ac4f" id="ac4f" class="graf--blockquote">In a nutshell, Living Style Guides are designed to aid building well-organized documentation of Front-end codebase. The “Living” part of it, means that documentation remains in constant sync with the actual code.</blockquote>

<h3 name="bfc1" id="bfc1" class="graf--h3">CSS Documentation</h3>

<p name="5fbc" id="5fbc" class="graf--p">The first players in the field are <em class="markup--em markup--p-em">CSS Documentation</em> parsing tools. The idea of combining description of components with styles source code first came from Web Designers. Combining creative approach and Design Style Guides success with web implementation practices has led to <a href="http://warpspire.com/kss/" data-href="http://warpspire.com/kss/" class="markup--anchor markup--p-anchor" rel="nofollow">KSS</a> development.</p>

<p name="b804" id="b804" class="graf--p">As you most probably have heard about it, I will quickly recap on the main idea behind it. Similar with <a href="https://github.com/jsdoc3/jsdoc" data-href="https://github.com/jsdoc3/jsdoc" class="markup--anchor markup--p-anchor" rel="nofollow">JSDoc</a>, CSS component description is set right in the source code comments.</p>

<pre name="eda8" id="eda8" class="graf--pre">// A button suitable for giving a star to someone.<br/>//<br/>// :hover             - Subtle hover highlight.<br/>// .star-given        - A highlight indicating.<br/>// .star-given:hover  - Subtle hover highlight.<br/>// .disabled          - Dims the button.<br/>//<br/>// Styleguide 2.1.3.</pre>

<pre name="8edf" id="8edf" class="graf--pre">a.button.star{<br/>  ...<br/>  &amp;.star-given{<br/>    ...<br/>  }<br/>  &amp;.disabled{<br/>    ...<br/>  }<br/>}</pre>

<p name="6235" id="6235" class="graf--p">KSS allows to define component section number and different states description. Which is then parsed by special tools, generating a single-page documentation or a set of static HTML files with rendered examples and code snippets.</p>

<figure name="b8e9" id="b8e9" class="graf--figure postField--insetLeftImage"><div class="aspectRatioPlaceholder is-locked"><p class="aspect-ratio-fill"/><img class="graf-image" data-image-id="1*VbgLdzU-OehiW7CEviDc0g.png" data-width="1183" data-height="1505" data-action="zoom" data-action-value="1*VbgLdzU-OehiW7CEviDc0g.png" src="https://d262ilb51hltx0.cloudfront.net/max/600/1*VbgLdzU-OehiW7CEviDc0g.png"/></div><figcaption class="imageCaption">KSS generated single page documentation.</figcaption></figure>

<p name="8cf1" id="8cf1" class="graf--p">In similar CSS Doc parsing tools, it is also possible to define the HTML markup in comments, when KSS only parses the actual CSS selectors and generates simple markup automatically.</p>

<p name="d37b" id="d37b" class="graf--p">Currently KSS is positioned as a documentation solution only, and the parsing tool is not getting new updates.</p>

<p name="9780" id="9780" class="graf--p graf--empty"><br/></p>

<p name="8293" id="8293" class="graf--p graf--empty"><br/></p>

<h4 name="29c6" id="29c6" class="graf--h4">KSS alternatives</h4>

<p name="c3d8" id="c3d8" class="graf--p">Since the original KSS, many similar tools have been presented to do exactly the same thing. One of the most successful implementations is <a href="http://styleguide.sc5.io/" data-href="http://styleguide.sc5.io/" class="markup--anchor markup--p-anchor" rel="nofollow">SC5 Style Guide</a>. In addition to encapsulated (using Shadow DOM) rendered component previews the tool also allows to edit SASS or LESS styles right in the browser. It is also possible to define Angular directives or Web components as a markup example in CSS comments, which will then be transformed into a fully operational component.</p>

<p name="246b" id="246b" class="graf--p">Unfortunately, most of the CSS Documentation tools are somewhat copying each other, without introducing any new possibilities. That is the reason why it is not worth to describe each tool separately, so I will just list the ones you can find out there — StyleDocco, Kalei Styleguide (client-side only), Hologram and Styledown.</p>

<p name="7527" id="7527" class="graf--p">Yet there is a tool with distinction. <a href="https://github.com/darcyclarke/DSS" data-href="https://github.com/darcyclarke/DSS" class="markup--anchor markup--p-anchor" rel="nofollow">DSS</a> is the only <em class="markup--em markup--p-em">standalone</em> CSS documentation parser, that produces JSON for later templating. Based on Node.js with support of all modern pre-processors. Comparing to KSS, it is possible to integrate DSS into any other tools and environments, as the original author also did with <a href="https://github.com/darcyclarke/grunt-dss" data-href="https://github.com/darcyclarke/grunt-dss" class="markup--anchor markup--p-anchor" rel="nofollow">Grunt plugin</a>.</p>

<h3 name="0975" id="0975" class="graf--h3">Style Guide Platforms</h3>

<p name="415e" id="415e" class="graf--p">The problem with CSS Documentation parsers is that they are very limited, nevertheless they are the easiest to implement. Trying to describe more complex components in CSS, you will end up with bloated and hard to manage styles, containing tons of copy-pasted HTML snippets all over the codebase.</p>

<p name="2338" id="2338" class="graf--p">The more of duplicated templates and HTML markup you have, the less <em class="markup--em markup--p-em">Living</em> are your Style Guides. Without constant sync between codebase and the pattern library, you may face more problems than with having no documentation at all.</p>

<p name="2b02" id="2b02" class="graf--p">Having big plans for maintaining own UI components library, it’s better to chose an alternative group of tools called <em class="markup--em markup--p-em">Style Guide Platforms</em>. Using both static-site generators and running dynamic environments, they provide more alternative and scalable solutions for collecting your documentation.</p>

<h3 name="c916" id="c916" class="graf--h3">Static Style Guide Generators</h3>

<p name="9e44" id="9e44" class="graf--p">Most basic example of static Front-end Style Guide generator is <a href="https://github.com/adactio/Pattern-Primer" data-href="https://github.com/adactio/Pattern-Primer" class="markup--anchor markup--p-anchor" rel="nofollow">Pattern Primer</a>. All it does is concatenating a list of HTML files into the one-page documentation, which you can enhance with a small text description and code examples.</p>

<p name="eaff" id="eaff" class="graf--p">The reason I started with it is that all the other tools I will mention in this section are doing almost the same thing, but with separate additional perks on top.</p>

<h4 name="6a07" id="6a07" class="graf--h4">Pattern Lab</h4>

<p name="73a8" id="73a8" class="graf--p"><a href="http://patternlab.io/" data-href="http://patternlab.io/" class="markup--anchor markup--p-anchor" rel="nofollow">Pattern Lab</a> is another tool for concatenating a set of templates into a static website. But on top of that it is also providing a set of useful features like navigation, annotation support and smart templating.</p>

<p name="58d0" id="58d0" class="graf--p">Every tool must have a workflow and Pattern Lab does it best, combining opinionated structure with <a href="http://bradfrost.com/blog/post/atomic-web-design/" data-href="http://bradfrost.com/blog/post/atomic-web-design/" class="markup--anchor markup--p-anchor" rel="nofollow">Atomic design</a> approach. This is an ideal combination for easy prototyping and passing HTML markup to client or back-end developers. Yet the opinion on technologies and file naming may interfere with existing codebase and special needs.</p>

<figure name="1f3d" id="1f3d" class="graf--figure"><div class="aspectRatioPlaceholder is-locked"><p class="aspect-ratio-fill"/><img class="graf-image" data-image-id="1*Uqk5QrR5BmAByuiTf1rjiA.png" data-width="915" data-height="703" data-action="zoom" data-action-value="1*Uqk5QrR5BmAByuiTf1rjiA.png" src="https://d262ilb51hltx0.cloudfront.net/max/800/1*Uqk5QrR5BmAByuiTf1rjiA.png"/></div><figcaption class="imageCaption">Folder structure and Pattern Lab generated navigation.</figcaption></figure>

<p name="f538" id="f538" class="graf--p">As an input to Pattern Lab static-site generator, user should prepare a <em class="markup--em markup--p-em">_patterns</em> catalog with folders for each component, following the naming convention. Each folder therefore contains a set of Mustache templates with HTML markup.</p>

<figure name="3933" id="3933" class="graf--figure"><div class="aspectRatioPlaceholder is-locked"><p class="aspect-ratio-fill"/><img class="graf-image" data-image-id="1*Fg1jJNbzGJ2ULnspXTI_hg.png" data-width="606" data-height="161" src="https://d262ilb51hltx0.cloudfront.net/max/800/1*Fg1jJNbzGJ2ULnspXTI_hg.png"/></div></figure>

<p name="1f76" id="1f76" class="graf--p">Data for templates is defined on a global level, or may be set locally next to the markup itself:</p>

<pre name="070c" id="070c" class="graf--pre">pages/article.mustache<br/>pages/article.json</pre>

<p name="40a1" id="40a1" class="graf--p">Then all is left is to link project styles into a generic page template and run the Pattern Lab builder. View the resulting <a href="http://demo.patternlab.io/" data-href="http://demo.patternlab.io/" class="markup--anchor markup--p-anchor" rel="nofollow">demo page</a> of generated pattern library.</p>

<h4 name="e7a4" id="e7a4" class="graf--h4">Other generators</h4>

<p name="ee0e" id="ee0e" class="graf--p">There are a few more tools, following same site-generator principles. <a href="http://fbrctr.github.io/fabricator" data-href="http://fbrctr.github.io/fabricator" class="markup--anchor markup--p-anchor" rel="nofollow">Fabricator</a> is gathering HTML and Markdown files, providing you better flexibility on structuring components documentation.</p>

<figure name="8716" id="8716" class="graf--figure"><div class="aspectRatioPlaceholder is-locked"><p class="aspect-ratio-fill"/><img class="graf-image" data-image-id="1*orRqPigNylwy1bSJMJKPow.png" data-width="1143" data-height="788" data-action="zoom" data-action-value="1*orRqPigNylwy1bSJMJKPow.png" src="https://d262ilb51hltx0.cloudfront.net/max/800/1*orRqPigNylwy1bSJMJKPow.png"/></div><figcaption class="imageCaption">Fabricator compatible folder structure and produced page screenshot.</figcaption></figure>

<p name="c382" id="c382" class="graf--p">As the Pattern Lab allows to define template data next to Mustache sources, with Fabricator it is possible to define Markdown file with text description next to the HTML source.</p>

<p name="844f" id="844f" class="graf--p">Documentation processing is done by using Gulp build task, which also includes Live reload for ease of development. Here is an <a href="http://fbrctr.github.io/fabricator/toolkit/" data-href="http://fbrctr.github.io/fabricator/toolkit/" class="markup--anchor markup--p-anchor" rel="nofollow">example output</a> generated by Fabricator.</p>

<h4 name="a699" id="a699" class="graf--h4">Living Style Guide Gem</h4>

<p name="0d89" id="0d89" class="graf--p">Another tool worth mentioning is <a href="http://livingstyleguide.org/" data-href="http://livingstyleguide.org/" class="markup--anchor markup--p-anchor" rel="nofollow">Living Style Guide Gem</a>, based on SASS and Markdown.</p>

<p name="fd37" id="fd37" class="graf--p">To define markup, you can choose between HTML and HAML. UI elements are described by using Markdown with custom syntax for imports and data definition.</p>

<pre name="0363" id="0363" class="graf--pre">@haml<br/>@full-width<br/>***.concept-page***<br/>  ***.concept-page--container***<br/>    %h1***.concept-page--title*** Concept<br/>    ***.concept-page--section***</pre>

<p name="a16b" id="a16b" class="graf--p">Here is a <a href="https://github.com/eurucamp/livingstyleguide-eurucamp/tree/2015/source/stylesheets/components" data-href="https://github.com/eurucamp/livingstyleguide-eurucamp/tree/2015/source/stylesheets/components" class="markup--anchor markup--p-anchor" rel="nofollow">list of demo components</a> used as an input to Living Style Guide generator and the resulting <a href="http://livingstyleguide.com/eurucamp/" data-href="http://livingstyleguide.com/eurucamp/" class="markup--anchor markup--p-anchor" rel="nofollow">single page doc</a>.</p>

<p name="8ea0" id="8ea0" class="graf--p">Since it follows quite opinionated technology stack, most benefits will be revealed only by utilizing Ruby ecosystem.</p>

<h3 name="4caf" id="4caf" class="graf--h3">Dynamic Style Guide Platforms</h3>

<p name="4767" id="4767" class="graf--p">To get even more flexibility and richer set of features you can choose <em class="markup--em markup--p-em">Dynamic Style Guide Platform</em>. The difference from all other tools mentioned above is the fact that it does not produce static website sources, but instead provides a full-featured web application.</p>

<p name="bbba" id="bbba" class="graf--p">For the time being, there are only two good examples of dynamic Style Guide Platforms — <a href="https://github.com/lonelyplanet/rizzo" data-href="https://github.com/lonelyplanet/rizzo" class="markup--anchor markup--p-anchor" rel="nofollow">Rizzo</a> and <a href="http://sourcejs.com/" data-href="http://sourcejs.com/" class="markup--anchor markup--p-anchor" rel="nofollow">SourceJS</a>.</p>

<blockquote name="0df8" id="0df8" class="graf--pullquote pullquote">Comparing to CSS focused tools, Style Guide Platforms are more engineer-driven, covering full development and integration process, not only the HTML markup and web design aspects.</blockquote>

<h4 name="c28c" id="c28c" class="graf--h4">Rizzo</h4>

<p name="b03e" id="b03e" class="graf--p">Rizzo is a small Ruby application, that pulls UI component assets via special API that master (main product) application provides. Instead of copying templates and markup into the Style Guide repository, component sources are pulled there automatically. It is currently the best way to develop truly <strong class="markup--strong markup--p-strong"><em class="markup--em markup--p-em">Living</em></strong> style guides, that are constantly in sync with the real codebase, thus providing more flexibility than CSS documentation parsers.</p>

<p name="191f" id="191f" class="graf--p">Unfortunately Rizzo is highly opinionated and is not yet suited for easy re-use in other applications, but I definitely suggest you reading more about ideas behind it on Lonely Planet <a href="https://github.com/lonelyplanet/rizzo" data-href="https://github.com/lonelyplanet/rizzo" class="markup--anchor markup--p-anchor" rel="nofollow">engineering blog</a>.</p>

<h4 name="dc9c" id="dc9c" class="graf--h4">SourceJS</h4>

<p name="8929" id="8929" class="graf--p">Compared to Rizzo, <a href="http://sourcejs.com/" data-href="http://sourcejs.com/" class="markup--anchor markup--p-anchor" rel="nofollow">SourceJS</a> is a scalable open source solution. The dynamic app environment allows to configure any custom routing and on the fly API based documentation page generation. Giving more freedom for integration with your main application sources like it’s done in Rizzo.</p>

<p name="0ccb" id="0ccb" class="graf--p">Out of the box, SourceJS allows to use Markdown files and special template pages for describing UI components. With official plugins, it is also possible to use <a href="https://github.com/sourcejs/sourcejs-contrib-dss" data-href="https://github.com/sourcejs/sourcejs-contrib-dss" class="markup--anchor markup--p-anchor" rel="nofollow">CSS Documentation</a> and <a href="https://github.com/sourcejs/sourcejs-jade" data-href="https://github.com/sourcejs/sourcejs-jade" class="markup--anchor markup--p-anchor" rel="nofollow">Jade</a> based templates. Chose preferred syntax or combine everything at once (see <a href="http://sourcejs.com/specs/" data-href="http://sourcejs.com/specs/" class="markup--anchor markup--p-anchor" rel="nofollow">examples</a>).</p>

<figure name="cdb6" id="cdb6" class="graf--figure graf--iframe"><p class="iframeContainer"/><figcaption class="imageCaption">SourceJS introduction video.</figcaption></figure>

<p name="f795" id="f795" class="graf--p">Core of the application is highly modular, containing only the most common features and API’s used for <a href="http://sourcejs.com/docs/api/plugins/" data-href="http://sourcejs.com/docs/api/plugins/" class="markup--anchor markup--p-anchor" rel="nofollow">developing custom plugins</a>. Platform is built with Node.js but does not provide any opinion on technologies you might want to integrate, like different templating languages and CSS pre-processors.</p>

<h4 name="91d7" id="91d7" class="graf--h4">Components Oriented</h4>

<p name="de3a" id="de3a" class="graf--p">SourceJS workflow is mostly focused on <em class="markup--em markup--p-em">component libraries</em> organization and is supporting Living Style Guide driven development rules. That helps to develop and test components right in the documentation pages.</p>

<p name="b673" id="b673" class="graf--p">This approach allows to combine multiple sets of components in one environment, even for different web projects. Simply put the main application next to SourceJS app and link CSS styles, JS and templates into documentation pages.</p>

<p name="9db1" id="9db1" class="graf--p">If project codebase is already focused on standalone UI components, link their folders to SourceJS spec catalog:</p>

<pre name="28cf" id="28cf" class="graf--pre">sourcejs/specs/<br/>    menu-component/<br/>        menu.css<br/>        menu.js<br/>        menu.html<br/>        readme.md<br/>        [index.src]</pre>

<p name="3b77" id="3b77" class="graf--p">Engine will parse the <em class="markup--em markup--p-em">readme.md</em> file or special <em class="markup--em markup--p-em">index.src</em> template with component representation examples and expose rich <a href="http://sourcejs.com/docs/spec/" data-href="http://sourcejs.com/docs/spec/" class="markup--anchor markup--p-anchor" rel="nofollow">documentation page</a>. Use this page to list all component states with different data, making it easier to test and share among team members.</p>

<p name="ee80" id="ee80" class="graf--p">Request a <a href="mailto:r@rhr.me" data-href="mailto:r@rhr.me" class="markup--anchor markup--p-anchor">consultation session</a> with the authors of the SourceJS platform to see how it could be integrated with your codebase. Or use GitHub issues and <a href="http://gitter.im/sourcejs/Source" data-href="http://gitter.im/sourcejs/Source" class="markup--anchor markup--p-anchor" rel="nofollow">Gitter chat</a> for questions.</p>

<h2 name="53b3" id="53b3" class="graf--h2">Starter Kits</h2>

<p name="3528" id="3528" class="graf--p">Most common misunderstanding I see around Style Guide tool compilations is that Starter kits are mixed together with generators and parsers. Treat them only as HTML5 boilerplate for upcoming Style Guide:</p>

<p name="ada4" id="ada4" class="graf--p">These starter templates could be used in any of mentioned tools, as a markup examples.</p>

<h2 name="bfe5" id="bfe5" class="graf--h2">Summing up</h2>

<p name="be9e" id="be9e" class="graf--p">If you find it hard to choose the right tool, let me help solving this question by summing up the main concerns.</p>

<p name="bf50" id="bf50" class="graf--p">I won’t focus on technologies on which these tools are based, because in most cases it does not matter if a generator or dynamic server is running on Ruby or Node.js. The thing that <em class="markup--em markup--p-em">really matters</em> is the organizational structure, used templating engines and platform flexibility.</p>

<h4 name="ef3f" id="ef3f" class="graf--h4">Starting from small</h4>

<p name="c1b5" id="c1b5" class="graf--p">For simple CSS Frameworks and small web projects, that are not planned for long-time support, I would suggest using <a href="http://styleguide.sc5.io/" data-href="http://styleguide.sc5.io/" class="markup--anchor markup--p-anchor" rel="nofollow">SC5 Style Guide</a> or <a href="https://github.com/darcyclarke/DSS" data-href="https://github.com/darcyclarke/DSS" class="markup--anchor markup--p-anchor" rel="nofollow">DSS</a>. Both of them are really easy to set up and master.</p>

<figure name="7914" id="7914" class="graf--figure"><div class="aspectRatioPlaceholder is-locked"><p class="aspect-ratio-fill"/><img class="graf-image" data-image-id="1*sY3tE8tmRlpcpd7ngV830A.png" data-width="923" data-height="460" data-action="zoom" data-action-value="1*sY3tE8tmRlpcpd7ngV830A.png" src="https://d262ilb51hltx0.cloudfront.net/max/800/1*sY3tE8tmRlpcpd7ngV830A.png"/></div><figcaption class="imageCaption">Simple CSS Components Library from Heroku.</figcaption></figure>

<h4 name="8001" id="8001" class="graf--h4">For more complex component libraries</h4>

<p name="009e" id="009e" class="graf--p">If you need to support components more complex than buttons and forms, containing many technologies like templates and JavaScript, the best choice will be the Style Guide Platforms. Comparing to CSS Documentation, Platforms allow following Style Guide Driven Development with all it’s benefits.</p>

<p name="51fe" id="51fe" class="graf--p">This combination will help you maintain a really Living pattern libraries, keeping codebase well structured and easy to reuse.</p>

<h4 name="bf34" id="bf34" class="graf--h4">Flexible solutions, for deep integration</h4>

<p name="859c" id="859c" class="graf--p">The only efficient and long-lasting way of supporting Living Style Guides is having no code duplication at all. <a href="https://github.com/lonelyplanet/rizzo" data-href="https://github.com/lonelyplanet/rizzo" class="markup--anchor markup--p-anchor" rel="nofollow">Rizzo</a> and <a href="http://sourcejs.com/" data-href="http://sourcejs.com/" class="markup--anchor markup--p-anchor" rel="nofollow">SourceJS</a> approach allows to seamlessly integrate development workflow with the documentation process. Write code once and use it both in the product application and in the Style Guide with descriptions and different states representation.</p>

<p name="3574" id="3574" class="graf--p">With SourceJS, it is possible to repeat almost all the workflows that other tools are offering, but with wider possibilities for custom integration and powerful plugins infrastructure.</p>

<h4 name="1891" id="1891" class="graf--h4">The future of Style Guides</h4>

<p name="75e1" id="75e1" class="graf--p">Since I am the main contributor to SourceJS, I will let myself mention few additional benefits of the engine, sharing our team’s vision about Style Guides future.</p>

<blockquote name="a887" id="a887" class="graf--pullquote pullquote">We believe that Style Guides must serve as an entry point to any Front-end related workflows for the whole team. Therefore, Style Guides should be treated more seriously than just a regular documentation or a brand guideline.</blockquote>

<p name="44cc" id="44cc" class="graf--p">Using plugins like <a href="http://github.com/sourcejs/sourcejs-comments" data-href="http://github.com/sourcejs/sourcejs-comments" class="markup--anchor markup--p-anchor" rel="nofollow">comments</a> or <a href="http://github.com/sourcejs/sourcejs-crowd-voice" data-href="http://github.com/sourcejs/sourcejs-crowd-voice" class="markup--anchor markup--p-anchor" rel="nofollow">crowd-voice</a>, teams are able to communicate between different departments within the Style Guide. Leaving their remarks and feedback in the place where components are developed, tested and maintained.</p>

<figure name="4667" id="4667" class="graf--figure"><div class="aspectRatioPlaceholder is-locked"><p class="aspect-ratio-fill"/><img class="graf-image" data-image-id="1*cJKUjG6OrJCl-9Y_Aouxdg.png" data-width="628" data-height="344" src="https://d262ilb51hltx0.cloudfront.net/max/800/1*cJKUjG6OrJCl-9Y_Aouxdg.png"/></div><figcaption class="imageCaption">SourceJS plugin for commenting the rendered UI examples.</figcaption></figure>

<p name="700b" id="700b" class="graf--p">Apart from in-place communication, we can combine different development tools in one place. Run live reload, linting and testing tools with a single command all together withing the Style Guide Platform. Integrate performance metrics results and provide optimization suggestions right on the documentation page. The possibilities are endless.</p>

<p name="0be7" id="0be7" class="graf--p">We are working on getting more different interactive documentation and various front-end infrastructure dashboards in one place, making an ultimate tool for the web developers.</p>

<p name="9776" id="9776" class="graf--p">If you also believe in the future of Style Guides and are willing to support this movement, we will be happy to see you in SourceJS community.</p>

<h3 name="a075" id="a075" class="graf--h3">Further Research</h3>

<p name="13b3" id="13b3" class="graf--p graf--empty"><br/></p>

<ul class="postList"><li name="4a64" id="4a64" class="graf--li"><a href="http://www.elementcss.com" data-href="http://www.elementcss.com" class="markup--anchor markup--li-anchor" rel="nofollow">Element CSS</a> — interesting approach of hosted service with on the fly Style Guide creation</li><li name="4501" id="4501" class="graf--li"><a href="http://patternry.com/" data-href="http://patternry.com/" class="markup--anchor markup--li-anchor" rel="nofollow">Patternry</a> — a service for storing and organizing Front-end Style Guides online</li><li name="ade6" id="ade6" class="graf--li"><a href="http://styleguides.io" data-href="http://styleguides.io" class="markup--anchor markup--li-anchor" rel="nofollow">styleguides.io</a> — a collection of tools, articles and other materials on the Style Guides</li><li name="6786" id="6786" class="graf--li"><a href="https://github.com/davidhund/styleguide-generators" data-href="https://github.com/davidhund/styleguide-generators" class="markup--anchor markup--li-anchor" rel="nofollow">An overview of Pattern Library Generators</a></li></ul>

<p name="54c5" id="54c5" class="graf--p">And here is the video of my latest talk on the corresponding topic:</p>

<figure name="544d" id="544d" class="graf--figure graf--iframe graf--last"><p class="iframeContainer"/><figcaption class="imageCaption">Maintaining Own Components Library with Living Style Guides.</figcaption></figure>
  </article>
</section>


<nav id="jumpto">
  <p>
    <a href="/david/blog/">Accueil du blog</a> |
    <a href="https://medium.com/@operatino/living-style-guide-tools-in-depth-overview-28cfffb92d05">Source originale</a> |
    <a href="/david/stream/2019/">Accueil du flux</a>
  </p>
</nav>

<footer>
  <div>
    <img src="/static/david/david-larlet-avatar.jpg" loading="lazy" class="avatar" width="200" height="200">
    <p>
      Bonjour/Hi!
      Je suis <a href="/david/" title="Profil public">David&nbsp;Larlet</a>, je vis actuellement à Montréal et j’alimente cet espace depuis 15 ans. <br>
      Si tu as apprécié cette lecture, n’hésite pas à poursuivre ton exploration. Par exemple via les <a href="/david/blog/" title="Expériences bienveillantes">réflexions bimestrielles</a>, la <a href="/david/stream/2019/" title="Pensées (dés)articulées">veille hebdomadaire</a> ou en t’abonnant au <a href="/david/log/" title="S’abonner aux publications via RSS">flux RSS</a> (<a href="/david/blog/2019/flux-rss/" title="Tiens c’est quoi un flux RSS ?">so 2005</a>).
    </p>
    <p>
      Je m’intéresse à la place que je peux avoir dans ce monde. En tant qu’humain, en tant que membre d’une famille et en tant qu’associé d’une coopérative. De temps en temps, je fais aussi des <a href="https://github.com/davidbgk" title="Principalement sur Github mais aussi ailleurs">trucs techniques</a>. Et encore plus rarement, <a href="/david/talks/" title="En ce moment je laisse plutôt la place aux autres">j’en parle</a>.
    </p>
    
    <p>
      Voici quelques articles choisis :
      <a href="/david/blog/2019/faire-equipe/" title="Accéder à l’article complet">Faire équipe</a>,
      <a href="/david/blog/2018/bivouac-automnal/" title="Accéder à l’article complet">Bivouac automnal</a>,
      <a href="/david/blog/2018/commodite-effondrement/" title="Accéder à l’article complet">Commodité et effondrement</a>,
      <a href="/david/blog/2017/donnees-communs/" title="Accéder à l’article complet">Des données aux communs</a>,
      <a href="/david/blog/2016/accompagner-enfant/" title="Accéder à l’article complet">Accompagner un enfant</a>,
      <a href="/david/blog/2016/senior-developer/" title="Accéder à l’article complet">Senior developer</a>,
      <a href="/david/blog/2016/illusion-sociale/" title="Accéder à l’article complet">L’illusion sociale</a>,
      <a href="/david/blog/2016/instantane-scopyleft/" title="Accéder à l’article complet">Instantané Scopyleft</a>,
      <a href="/david/blog/2016/enseigner-web/" title="Accéder à l’article complet">Enseigner le Web</a>,
      <a href="/david/blog/2016/simplicite-defaut/" title="Accéder à l’article complet">Simplicité par défaut</a>,
      <a href="/david/blog/2016/minimalisme-esthetique/" title="Accéder à l’article complet">Minimalisme et esthétique</a>,
      <a href="/david/blog/2014/un-web-omni-present/" title="Accéder à l’article complet">Un web omni-présent</a>,
      <a href="/david/blog/2014/manifeste-developpeur/" title="Accéder à l’article complet">Manifeste de développeur</a>,
      <a href="/david/blog/2013/confort-convivialite/" title="Accéder à l’article complet">Confort et convivialité</a>,
      <a href="/david/blog/2013/testament-numerique/" title="Accéder à l’article complet">Testament numérique</a>,
      et <a href="/david/blog/" title="Accéder aux archives">bien d’autres…</a>
    </p>
    <p>
      On peut <a href="mailto:david%40larlet.fr" title="Envoyer un courriel">échanger par courriel</a>. Si éventuellement tu souhaites que l’on travaille ensemble, tu devrais commencer par consulter le <a href="http://larlet.com">profil dédié à mon activité professionnelle</a> et/ou contacter directement <a href="http://scopyleft.fr/">scopyleft</a>, la <abbr title="Société coopérative et participative">SCOP</abbr> dont je fais partie depuis six ans. Je recommande au préalable de lire <a href="/david/blog/2018/cout-site/" title="Attention ce qui va suivre peut vous choquer">combien coûte un site</a> et pourquoi je suis plutôt favorable à une <a href="/david/pro/devis/" title="Discutons-en !">non-demande de devis</a>.
    </p>
    <p>
      Je ne traque pas ta navigation mais mon
      <abbr title="Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33.184162340">hébergeur</abbr>
      conserve des logs d’accès.
    </p>
  </div>
</footer>
<script type="text/javascript">
  ;(_ => {
    const jumper = document.getElementById('jumper')
    jumper.addEventListener('click', e => {
      e.preventDefault()
      const anchor = e.target.getAttribute('href')
      const targetEl = document.getElementById(anchor.substring(1))
      targetEl.scrollIntoView({behavior: 'smooth'})
    })
  })()
</script>