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 RunnerSprungmarke

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-StyleguideSprungmarke

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 umwandelnSprungmarke

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