Build a Style Guide Straight from Sass

Last fall, our dev team wanted to get started with style guides. We had added a new member to the team, and as he was getting up to speed, we realized how lacking our project documentation was. If you’ve ever been a new developer on a team with weak documentation, you know how confusing it can be to try to familiarize yourself with a dozen projects without documentation.

In deciding on a style guide method, we came up with two main requirements

1. Low FrictionThe style guide should be easy to find, easy to read, and easy to maintain. Something that fit into our existing development workflow would be awesome. Adding new directories for sample markup and documentation files would not be awesome.
2. Platform AgnosticWe work in WordPress, Drupal, and CakePHP most often, and we wanted something that would work the same way across all three platforms. We wanted this to be easily maintainable, and for us that meant keeping the documentation alongside the CSS.

Die Grundlagen von Node-KSS

Um unsere Ziele eines plattformunabhängigen, reibungslosen Styleguides zu erreichen, haben wir uns für kss-node entschieden, eine Node.js-Implementierung von Knyle Style Sheets (KSS), einer Ruby-Bibliothek, die

… eine Methodik für das Schreiben von wartbarem, dokumentiertem CSS in einem Team bietet. Insbesondere ist KSS eine Dokumentationsspezifikation und ein Styleguide-Format.

Das Grundprinzip ist, dass Ihr Styleguide über Kommentare generiert wird, die Sie in Ihrem CSS, SCSS, Sass, LESS usw. erstellen.

Sie schreiben CSS wie dieses

// Bold Button
//
// Use this class for a bolder, stronger looking button.
//
// Markup:
// <button class="btn btn-bold">Click Me</button>
//
// Styleguide Components.Buttons.bold
.btn.btn-bold {
    position: relative;
    font-weight: bold;
    text-transform: uppercase;
}

Und erhalten diese schöne Ausgabe

Sie können Ihre Dokumentation beliebig organisieren und sie generiert auch eine schöne kleine Navigations- und Dokumentationsstruktur für Sie.

Da es sich in Ihrem CSS befindet, passt die Aktualisierung natürlich in bestehende Entwicklungs-Workflows. Wenn Sie einige CSS-Eigenschaften aktualisieren, wird der Styleguide automatisch aktualisiert. Wenn Sie die Dokumentation aktualisieren müssen, befindet sich der Dokumentationstext direkt über der Komponente, an der Sie gerade arbeiten. Selbst wenn Sie den generierten Styleguide nie besuchen, sehen Sie den Styleguide jedes Mal, wenn Sie eine CSS-Datei öffnen. Geringe Reibung? Check.

Da wir außerdem CSS und Build-Prozesse in all unseren Webprojekten verwenden, ist es so plattformunabhängig, wie wir es brauchen.

Legen wir los!

Ersteinrichtung

In Ihrem Projektverzeichnis möchten Sie kss-node als Projekt-Abhängigkeit installieren. Wir werden auch michelangelo installieren, ein schönes Theme für den Styleguide.

$ npm install --save-dev kss michelangelo

Sie können überprüfen, ob es installiert wurde, indem Sie Folgendes ausführen:

$ ./node_modules/.bin/kss --version

Wir erstellen eine Datei namens kss-config.json, um unsere KSS-Einstellungen zu konfigurieren.

Erstellen Sie in Ihrer Datei ein Objekt wie dieses (beachten Sie, dass meine Kommentare unten nur zur Referenz dienen, entfernen Sie sie für beste Ergebnisse aus Ihrer Konfigurationsdatei)

{
  "title": "Title of the Style Guide",

  // Source tells KSS where the CSS, Sass, or SCSS is that it should parse for documentation comments. 
  // Here we are assuming your sass is in a directory at the root level of your project.
  "source": "sass/",

  // Destination tells KSS where to compile your style guide to.
  "destination": "styleguide/",

  // Builder tells KSS where to look for a theme. 
  // If you aren't using michelangelo, you don't need this.
  "builder": "node_modules/michelangelo/kss_styleguide/custom-template/",

  // CSS gives KSS the path to your CSS, so it can pull your styles into the style guide. 
  // The path needs to be relative to your style guide destination.
  // Here, our style guide is in /styleguide and our compiled css is at our project root.
  "css": [
    "../main.css"
  ],

  // If you want to include any javascript files, add this block, with the path to your javascript file. 
  // Also relative to your style guide destination.
 // Optional.
  "js" : [
    "../bundle.js"
  ]
}

Dies setzt einen einfachen Projektverzeichnisbaum voraus, der so aussieht:

js/
sass/
bundle.js
index.html
main.css

Sie können versuchen, Ihren Styleguide zu kompilieren, indem Sie Folgendes ausführen:

$ ./node_modules/.bin/kss --config kss-config.json

Wenn Sie einen saubereren Befehl zum Ausführen wünschen, fügen Sie ein Skript zum Skriptblock in Ihrer `package.json` hinzu.

"scripts": {
  "kss": "kss --config kss-config.json"
},

Jetzt können Sie $ npm run kss ausführen, um Ihren Styleguide zu kompilieren. (Ich werde diese Methode weiterhin verwenden, aber Sie können $ ./node_modules/.bin/kss --config kss-config.json verwenden, wenn Sie möchten).

Da wir jedoch noch keine Dokumentation geschrieben haben, erhalten Sie wahrscheinlich eine Meldung wie:

Error: No KSS documentation discovered in source files.

Lassen Sie uns das beheben, indem wir unsere erste Komponente dokumentieren!

Erstellen und Dokumentieren einer einfachen Komponente

Wir erstellen eine Beispiel-Post-Titel-Komponente.

Hier ist unser CSS

.post-title {
  font-size: 3em;
  text-align: center;
  font-family: fantasy;
}

Um unsere Dokumentation zu erstellen, erstellen wir einen Kommentar

// Post Title (this will be the title of your component)
//
// Large, **in charge**, and centered. (this is the description of your component. you can use markdown in here.)
//
// Markup (define the markup to be used in your styleguide):
// <h1 class="post-title">A Post Title</h1>
//
// Styleguide Components.article.post-title 
// (ꜛ this controls the organization of your style guide. Here, I'm filing this component inside Components / Article / Post Title) 

.post-title { 
    font-size: 3em; 
    text-align: center;
    font-family: fantasy; 
}

Führen Sie $ npm run kss aus, und Ihr Styleguide sollte kompiliert werden! Sie können darauf über den Zielpfad zugreifen, den Sie ihm gegeben haben. In diesem Beispiel haben wir eine statische Website und ich habe sie in /styleguide kompiliert, also das ist die URL, die ich verwenden werde, um sie zu finden. So sollte es aussehen, wenn Sie das michelangelo-Theme verwenden (ich habe die Kommentare in Klammern entfernt)

Hier ist, was passiert ist

1. KSS hat einen Dokumentationsbereich für unseren Post-Titel erstellt, komplett mit Titel, Beschreibung, Markup und CSS, die wir bereitgestellt haben. Sie können das gerenderte HTML und CSS sowie das rohe HTML sehen.
2. KSS hat gesehen, dass wir unseren Post-Titel unter Components / Article verschachtelt haben, also hat es eine top-level Sektion Components und eine Sektion Components.article erstellt. Unser Post-Titel ist unter beiden verschachtelt.
3. KSS hat basierend auf dieser Hierarchie eine Navigation generiert.

Wenn Sie weitere Informationen zu Components bereitstellen möchten, können Sie einen Dokumentationsblock (irgendwo in Ihrem CSS) wie folgt bereitstellen:

// Components
//
// Components are ingredients of our design system. They may be made up of smaller groups of styles.
//
// Styleguide Components

Ebenso könnten Sie weitere Informationen zur Artikelkomponente bereitstellen, indem Sie einen Dokumentationsblock definieren, der über die Methode Styleguide Components.article auf dieses Element abzielt.

// Article
//
// An article is made up of a title, featured image, and some default
// typographic settings for links, italics, bold, and blockquotes.
//
// Styleguide Components.article

Mit diesen neuen Dokumentationsblöcken kompilieren Sie Ihren Styleguide erneut ($ npm run kss), und Sie werden sehen, dass Ihre Gliederung etwas voller ist.

Dokumentation von Komponenten-Zuständen und -Varianten

Unsere Post-Titel-Komponente ist sehr einfach, aber wir müssen komplexere Informationen in unserem Styleguide anzeigen. KSS kann Variationen von Komponenten sowie interaktive Zustände wie :hover oder :focus problemlos verarbeiten. Wir dokumentieren einen Button, um dies zu zeigen.

Unser Button hat unterschiedliche Stile für :focus und :hover, sowie eine kleine und eine große Variante. Hier ist das CSS, mit dem wir beginnen werden:

.button {
  padding: 1em 2em;
  margin: .5em;
  display: inline-block;
  font-size: .9em;
  font-family: Helvetica, sans-serif;
  font-weight: bold;
  text-transform: uppercase;
  color: #f56476;
  background-color: #fff;
  border: 2px solid #f56476;
  transition: .2s color, .2s background-color, .2s border-color;
}

.button:hover {
  color: #fff;
  background-color: #f56476;
}

.button:focus {
  color: #3ddc97;
  border-color: currentColor;
}

.button--small {
  font-size: .5em;
}

.button--large {
  font-size: 1.5em;
}

Wir formatieren unsere Dokumentation genauso wie für unseren Post-Titel mit zwei Ergänzungen: Wir fügen eine Platzhalterklasse von {{modifier_class}} zu all unseren Elementen hinzu, die den Modifikator erhalten, und wir definieren unsere Zustände / Variationen direkt unter unserem Markup. Unser Kommentarblock sieht dann so aus (ich habe einige Notizen in Klammern hinzugefügt):

// Buttons (title, same as before)
//
// Various button styles. (description, just as before)
//
// Markup: (we add the `{{modifier_class}}` to every element that has a modifier)
// Link Button
// <button class="button {{modifier_class}}">Button Element</button>
// <input class="button {{modifier_class}}" type="button" value="Input Button" />
//
// (a new modifiers section)
// :hover - When user hovers over button.
// :focus - When button is focused.
// .button--small - A small button.
// .button--large - A large button.
//
// Styleguide Components.button (organization, just as before)

Sie können sehen, dass ich eine Variante für jede der von mir in meinem CSS deklarierten Variationen hinzugefügt habe. Das Format ist:

// .class-name - Description

oder

// :state - Description

Wenn der Styleguide kompiliert wird, erhalten Sie diese neue Dokumentation:

Sie sehen, dass Sie jetzt ein Beispiel für jeden der Zustände und Variationen haben, die Sie im Modifikatorteil beschrieben haben, mit dem entsprechenden angewendeten CSS.

Diese Technik funktioniert auch für komplexere Komponenten als diesen Button. Nehmen wir an, Sie haben eine .card-Komponente mit inneren Elementen, die sich ändern müssen, wenn ein Benutzer mit der Maus über die Karte fährt. Um dies zu dokumentieren, würden Sie {{modifier_class}} nur zum .card-Element hinzufügen und den Hover-Zustand genauso angeben wie oben.

Organisation

Standardmäßig werden die Abschnitte alphabetisch nach ihrem Titel sortiert. Zum Beispiel kommt unsere Button-Komponente nach unserer Artikelkomponente in den obigen Beispielen. Wenn Sie jedoch die Reihenfolge von Komponenten oder anderen Abschnitten ändern möchten, können Sie der Komponente ein Gewicht zuweisen. Ein höheres Gewicht bringt die Komponente tiefer in ihrem Abschnitt. Ein niedrigeres Gewicht bringt die Komponente höher im Abschnitt.

Wenn Sie Sass oder SCSS verwenden, platziere ich meine Organisationskommentare in meiner main.sass oder wo immer ich meine Partials importiere. Zum Beispiel hatte ich bei einem kürzlichen Projekt einen Typography-Abschnitt und einen Elements-Abschnitt, die beide unter einer Base-Top-Level-Sektion abgelegt waren. Natürlich würde KSS diese Abschnitte alphabetisch organisieren, aber ich wollte, dass Typography zuerst kommt. Hier ist, wie ich das Gewicht in meiner main.sass-Datei geändert habe:

// Typography
//
// Weight: 1
//
// Styleguide base.typography
@import "base/typography"

// Elements
//
// Weight: 2
//
// Styleguide base.elements
@import "base/elements"

Farbpaletten

Das Michelangelo-Theme, das wir verwenden, bietet einen coolen Farbpaletten-Generator. Wenn Sie Sass oder SCSS verwenden, können Sie Ihre Farbvariablennamen dokumentieren, und KSS formatiert einen kleinen Farbpalettenblock.

Mit einem Kommentar wie diesem

// Highlight Colors
//
// Colors we use for higlighting states.
//
// $highlight-blue - #1460aa; primary blue
// $highlight-purple - #674172; secondary purple
// $highlight-red - #d50000; danger red
//
// Styleguide Base.colors

KSS erstellt eine Farbpalette zur einfachen Referenz wie diese

Automatisches Kompilieren des Styleguides

Anstatt jedes Mal $ npm run kss auszuführen, wenn wir eine Änderung am CSS vornehmen, können wir eine Watch-Task hinzufügen, um den Styleguide jedes Mal neu zu generieren, wenn unsere CSS-Dateien geändert werden. Ich werde als Nächstes dokumentieren, wie das mit npm Scripts und über Grunt geht.

npm Skripte

Wir verwenden bereits npm-Skripte, um den Styleguide zu erstellen. Wir müssen nur noch ein Skript hinzufügen, das unseren Styleguide beobachtet.

Wir werden das onchange-Paket verwenden. Installieren Sie es zuerst.

$ npm install onchange --save-dev

Fügen Sie dann ein neues Skript in unserem Skriptobjekt hinzu.

"scripts": {
  "watch": "onchange 'sass/**/*.sass' -- npm run kss",
  "kss": "kss --config kss-config.json"
},

Die Watch-Task weist onchange an, die Dateien zu beobachten, die wir in unserem Glob-Muster ('sass/**/*.sass') angegeben haben, und wenn sie eine Änderung erkennt, den Befehl auszuführen, den wir nach -- angeben: npm run kss.

Wenn Sie jetzt $ npm run watch ausführen, werden Ihre .sass-Dateien überwacht und Ihr Styleguide wird jedes Mal neu generiert, wenn eine Änderung in Ihrem Sass erkannt wird.

Grunt

Es gibt ein offizielles Grunt-Plugin für KSS, grunt-kss. Sie können es konfigurieren, um Ihre .sass- oder .scss-Dateien auf Änderungen zu überwachen und den Styleguide während der Entwicklung neu zu kompilieren.

Hier ist eine Beispiel-Grunt-Konfiguration. Mit dieser Einrichtung benötigen Sie keine separate kss-config.json-Datei, die gesamte Konfiguration kann in Ihrer Gruntfile erfolgen.

module.exports = function(grunt) {
  grunt.initConfig({
    kss: {
      options: {
        title: 'Title of the Style Guide',
        builder: "./node_modules/michelangelo/kss_styleguide/custom-template/",
        css: [
          "../path/to/compiled/css.css",
        ],
        js: [
          "../path/to/compiled/javascript.js",
        ]
      },
      dist: {
        src: "path/to/css/src",
        dest: "styleguide/",
      }
    },
    watch: {
      sass: {
        files: [
          './path/to/**/*.sass'
        ],
        tasks: ['kss']
      },
    }
  });

  grunt.loadNpmTasks('grunt-kss');
  grunt.loadNpmTasks('grunt-contrib-watch');

  grunt.registerTask('dev', ['kss', 'watch']);
}

Wenn Sie $ grunt dev ausführen, wird zuerst der Styleguide generiert, dann werden Ihre .sass-Dateien auf Änderungen überwacht und der Styleguide neu generiert, wenn eine Änderung erkannt wird.

Zusammenfassung

Weitere Details zur Kommentar-Analyse und anderen Funktionen, die ich hier nicht erwähnt habe, finden Sie im offiziellen KSS-Repository. Sie haben hier mehr als genug, um anzufangen, aber es gibt einige Dinge, auf die ich nicht eingegangen bin, darunter eine benutzerdefinierte Startseite, experimentelle/veraltete Flags und Helfer für Präprozessoren.

Wenn Sie noch weiter gehen möchten, können Sie Ihren eigenen Styleguide anstelle des von uns verwendeten Michelangelo-Themes entwickeln. Lesen Sie die Dokumentation zur Verwendung benutzerdefinierter Vorlagen für weitere Informationen.