Styleguide Ausschnitt

Styleguide generieren mit Sass & Grunt

Ein in größeren Projekten immer wichtiger werdendes Thema ist in meinen Augen ein Styleguide, der einerseits als Dokumentation und andererseits für externe Dienstleister als Referenz genutzt werden kann.

Früher™ als man das Design ausschließlich in Photoshop machte, wurde natürlich auch der Styleguide in Photoshop erstellt — mit Bemaßung LOL! Diese Vorlage sollten Webentwickler dann nutzen, um ein Design möglichst pixelgenau umzusetzen. Ich kann mich an keinen „Styleguide“ erinnern, der zu 100% stimmte. Häufig waren Fehler in der „Bemaßung“ oder in Farbwerten… ihr kennt das.

Die „gedruckten“ Styleguides sind natürlich nicht mehr zeitgemäß. Im Responsive Webdesign können Webseiten-Elemente in unterschiedlichen Ausgabegrößen unterschiedlich dargestellt werden. Zudem werden im agilen Responsive Workflow Designelemente auch geändert und sehen u.U. nicht mehr so aus, wie es der Designer geplant hatte.

(Anekdote am Rande: Im aktuellen Projekt wurde das Aussehen bei ca. ¾ der Elemente/Module während des agilen Entwicklungsprozess nach Rücksprache mit dem Designer geändert)

Ein „Living Styleguide“, der das Projekt widerspiegelt (also vielleicht responsive ist) und bei Veränderungen ohne großen Aufwand neu generiert wird, brauchte man. Gibt es! Grunt zu Hülf! :)

Grunt – The JavaScript Task Runner

Grunt ist ein Kommandozeilen „Task Runner“, mit dem man automatisiert Aufgaben erledigen lassen kann. Zum Beispiel kann man JavaScript auf Validität oder sauberer Schreibweise mit „jslint/jshint“ überprüfen oder Sass kompilieren und eine Vielzahl weiterer Tasks erledigen lassen. Tiefer will ich nicht auf Grunt(d)lagen eingehen, gute Einsteigerartikel findet ihr unter:

Grunt-Styleguide

Automatisierung von Webentwicklungsaufgaben ist super. Da liegt es natürlich nahe, auch Styleguides automatisiert erstellen zu lassen. Mit Grunt-Styleguide gibt es ein Grunt-Modul, das das für uns erledigen kann.

Installation von Grunt-Styleguide:

npm install grunt-styleguide --save-dev

Die Grunt-Modul-Konfiguration lässt zwei „Styleguide-Frameworks“ zu. Per Default ist Styledocco aktiv. Styledocco lässt allerdings keine eigenen Styleguide-Vorlagen zu. Das andere Framework, das mit Grunt-Styleguide verwendet werden kann, ist KSS-node und ist ebenfalls bereits im Modul enthalten. Der Node.js-Port von KSS, das für die Styleguide-Generierung des Github.com Styleguide verwendet wird, eignet sich meiner Meinung nach besser um individuelle Styleguides zu generieren.

Styleguide-Konfiguration in gruntfile.js:

// only the styleguide part of the gruntfile.js
styleguide: {
    options: {
        template: {
            src: 'styleguide/template/'
        },
        framework: {
            name: 'kss'
        }
    },
    all: {
        files: [{
            'dist/styleguide': 'css/sass/**/*.scss'
        }]
    }
}

grunt.registerTask('build', [], function () {
    grunt.loadNpmTasks('grunt-styleguide');
    grunt.task.run('styleguide');
});

Styleguide-Vorlage
Mit KSS-node ist es möglich, ein eigenes Styleguide-Template zu verwenden und somit den Styleguide an das Look and Feel des Projektes anzupassen.

Im Grunt-Modul ist unter templates/kss/index.html eine Beispiel-Datei hinterlegt. Diese Vorlage kann man in ein anderes Verzeichnis kopieren und nach belieben anpassen. Das Template ist mit Handlebars Helpern ausgestattet, um eine flexible Ausgabe der Daten zu ermöglichen.

Styleguide-Navigation in der Styleguide-Vorlage:

<ul class="styleguide-navigation">
  {{#eachRoot}}
    <li>
      <a href="section-{{reference}}.html">
        {{reference}}.0: {{header}}
      </a>
    </li>
  {{/eachRoot}}
</ul>

Soweit, so gut. Das Styleguide-Template liegt vor und der Grunt-Task ist konfiguriert, jetzt nur noch den Sass-Code kommentieren und der Styleguide kann erstellt werden.

Sass Kommentare in Styleguide umwandeln

Die einzelnen Styleguide-Abschnitte werden anhand von Kommentaren im CSS bzw. direkt aus den Sass-Kommentaren generiert. Das hat gleichzeitig den Vorteil, dass Entwickler ihren Code kommentieren. :)

Ein Beispiel:

// Links
//
// usual links and style for external links
//
// Markup: <a href="" class="{$modifiers}">Link</a>
//
// :visited  - visited styles
// :hover    - Highlight the button when hovered.
// :focus    - focus styles
// :active   - "Press" the button down when clicked.
// .external - external link styles
//
// Styleguide 1.1

a {
  color: $link-color;
  text-decoration: underline;

  &:visited {
    color: $link-colorV;
  }
  &:hover {
    color: $link-colorH;
  }
  &:focus {
    color: $link-colorF;
    outline: thin dotted;
  }
  &:active {
    color: $link-colorA;
    outline: none;
  }
  &:hover, &:active {
    outline: none;
  }
  &.external {
    color: $link-external;
  }
}

In den Kommentaren kann man mehrere Teile der Styleguide-Section Beschreibung unterbringen.

// Titel
//
// Beschreibung
//
// Markup: 
// <div>
//   <span>HTML-Code</span>
//   <span>mehrzeilig</span>
// </div>  
//
// Modifiers ({$modifiers}) 
// z.B. Pseudo-Klassen oder Modifier-Klassen 
// plus Beschreibung 
//
// Styleguide Abschnitt (1.1)

Als großer Unterschied zum original KSS Styleguide, der auf Ruby basiert, ist es mit KSS-node möglich über den „Markup-Teil“ in den Kommentaren auch Markup-Beispiele im Styleguide anzuzeigen. Zudem wird pro Modifier das Markup mit der Modifier-Klasse in den Styleguide eingefügt. Bei Pseudo-Klassen wie :hover wird das Styling dann per JavaScript (kss.js) on-the-fly eingesetzt.

Die freie Gestaltung des Markups lässt natürlich auch zu, dass man ganze Seitenmodule im Styleguide abbilden kann.

Beispiel Suchfeld:

// Search
//
// Below are global search field and search result list styles
//
// Styleguide 4

// global search field
//
// Markup:
// <form action="" class="global-search">
//   <fieldset>
//     <label for="search_field">Search</label>
//     <input type="search" id="search_field" 
//            name="search_field" 
//            placeholder="enter search term">
//     <button type="submit" class="btn-submit">Search</button>
//   </fieldset>
// </form>
//
// Styleguide 4.1

Ich habe in den Styleguide noch den Prism-Syntax-Highlighter von Lea Verou integriert, et voilà, der Living-Styleguide nimmt Formen an.

Screenshots

Styleguide3

(leider aktuell nur Screenshots vom Styleguide bis der veröffentlicht wird)

5 thoughts on “Styleguide generieren mit Sass & Grunt”

  1. Das sieht wirklich sehr gut aus. Kann man einen solchen Styleguide mit Pattern Lab von Brad Frost vergleichen?
    Beide scheinen einen leicht unterschiedlichen Ansatz zu verfolgen. Der Grunt-Styleguide (am Beispiel KSS) scheint eher einen beschreibenden Styleguide zu liefern, welcher Kommentare direkt aus den Stylesheets (oder Sass) generiert, während Pattern Lab eher die Visualisierung des Atomic Design widerspiegelt.
    Daher die Frage: Sollte man beide nutzen oder sich doch für eine Lösung entscheiden?
    Mir persönlich gefällt ein Styleguide mit lesbaren Kommentaren (KSS) besser. Allerdings hat Pattern Lab bei der Responsive Darstellung und der Kombination von Elementen zu Modulen bis hin zu Templates und ganzen Seiten Vorteile.

  2. Ich sehe Brads PatternLab eher als Baukasten um mit Elementen und Modulen dann Templates zu bauen. Ein Styleguide hat für mich, wie du schon sagst, auch was beschreibenes, vor allem der ausgegebene Quellcode ist für die Backend-Entwickler sehr hilfreich.

  3. Hi Sven,
    auf der github seite des Projekts steht zu den frameworks, dass kss-node nur less versteht, oder aber ich verstehe da was falsch. Du schreibst ja, dass Du/es mit sass funzt?
    will ich auf jeden fall auch ausprobieren, danke für den hint.
    gruss
    Tom

  4. Hi Sven,

    kannst du vielleicht etwas mehr dazu schreiben, wie du prism in das kss Template eingebunden hast? Würde mich sehr interessieren.
    Gruß
    Michael

  5. Hallo Michael,
    das ist nicht so kompliziert, im KSS-Template im HEAD die CSS-Datei einbinden:
    <link rel=“stylesheet“ href=“public/prism.css“>

    Im Body den Code mit der Klasse „language-markup“ (und „line-numbers“) auszeichnen:
    <pre class=“line-numbers language-markup“><code>{{markup}}</code></pre>
    und vorm schließenden BODY-Tag die prism.js einbinden:
    <script src=“public/prism.js“></script>

Kommentare sind geschlossen.