So erstellen Sie einen Living Style Guide

Die Verwendung eines Living Style Guides (LSG) zur Förderung der Entwicklung ist eine Praxis, die sehr beliebt ist, da sie viele Vorteile bietet, einschließlich Code-Effizienz und UI-Konsistenz. Aber wie können Sie einen erstellen? Was solltest du mit einschließen? Und wo fängst du überhaupt an? In diesem Tutorial werde ich mich mit den wesentlichen Details der Erstellung eines Lebensstils beschäftigen DokumentCSS .

Die Schönheit der Living Style Guides

Ähnlich wie ein Standard-Style-Guide bietet ein Living Style-Guide eine Reihe von Standards für die Verwendung und Erstellung von Stilen für eine Anwendung. Im Falle eines Standard-Styleguides ist es das Ziel, Markenkohärenz zu erhalten und den Missbrauch von Grafiken und Designelementen zu verhindern. Auf die gleiche Weise werden LSGs verwendet, um Konsistenz in einer Anwendung zu erhalten und deren Implementierung zu steuern. Aber was ein LSG anders und leistungsfähiger macht, ist die Tatsache, dass ein Großteil seiner Informationen direkt aus dem Quellcode stammt, sodass der sich entwickelnde Zustand einer Anwendung einfach und effizient abgebildet werden kann.

Selbst heute ist es überwältigend zu erfahren, dass Sie den Quellcode Ihrer Anwendung zum Erstellen Ihres Styleguides verwenden können.

Wenn Sie sich die Beispiele unten ansehen, werden Sie die gemeinsamen Nenner eines LSG sehen:

Eine Liste der Elemente, die dokumentiert sind
Präzise Dokumentation mit Code-Snippets und interaktiven UI-Demonstrationen

Lonely Planet Style Guide

Sales Force-Styleguide

Ein weiteres Schlüsselelement einer LSG ist, dass Sie einen Styleguide-Generator verwenden können, um den Prozess zu automatisieren. Ein Styleguide-Generator verwendet Ihren Anwendungsquellcode, um den Großteil Ihrer LSG-Dokumentation zu füttern und nach Änderungen in Ihrem Code zu suchen. Er sorgt dafür, dass Ihre Styleguide-Dokumentation aktualisiert wird, wenn sich Ihre Anwendung ändert.

Style Guide Generatoren

Je nach der Sprache, die Sie dokumentieren möchten, oder Ihrer Projektkonfiguration können Sie aus verschiedenen Varianten auswählen. Hier sind einige Orte, um nach Optionen zu suchen:

Eine detaillierte Übersicht der Living Style Guide Tools , Robert Haritonov, Smashing Magazine
Überblick über Musterbibliotheksgeneratoren , David Hund, GitHub
Style Guide Generator Zusammenfassung , Susan Robertson, Eine Liste Apart
Style-Guide-Tools , Website Style Guide Ressourcen

In diesem Tutorial zeige ich Ihnen, wie Sie mit DocumentCSS Ihr LSG erstellen können. Dieses von Bitovi erstellte Tool ist Open Source und kann in jedem Projekt zur Dokumentation von CSS verwendet werden (Präprozessoren wie Less und SASS werden ebenfalls unterstützt). Wenn Sie daran interessiert sind, Javascript und andere Sprachen zu dokumentieren, können Sie dies einfach mit DocumentCSS tun, da dieses Tool eine Untergruppe von DocumentJS ist. Ich werde diesen Teil in diesem Tutorial nicht behandeln, aber es ist gut, daran zu denken.

Planen Sie Ihren Style Guide

Bevor Sie mit der Erstellung Ihres LSG beginnen, ist der erste Schritt geplant, was darin enthalten ist. Wie bei jeder guten Website ist eine gut strukturierte Informationsarchitektur (IE) der Schlüssel.

Beginnen wir also mit den folgenden Designs unserer Beispiel-App namens "Vintage Shop" und beobachten Sie die persistenten Elemente in der Benutzeroberfläche:

Vintage Shop Mockups

An dieser Stelle empfehle ich, mit größeren Elementgruppen wie der Navigation, dem Einkaufswagen oder den Formularen zu beginnen. Zum Beispiel werden wir unser Design in diese drei Gruppen aufteilen: den Stufen-Indikator, den Mini-Einkaufswagen und die Produkte im Einkaufswagen:

Mit diesen größeren Elementgruppen können Sie anfangen, detaillierter zu gehen und die "Stile" zu identifizieren, die bestehen bleiben. Beispielsweise gibt es eine Konvention für die Typografie im Allgemeinen und insbesondere für die Überschriften, Unterüberschriften und Links im Vergleich zu normalem Text. Die Farbe der Schaltflächen bleibt auch auf den Seiten bestehen.

Lassen Sie uns diese Gruppen zusammenfassen, indem wir ein Diagramm verwenden:

Wenn Sie sich diese Gruppen genauer ansehen, können Sie sie verfeinern und in Kategorien umwandeln, die Sie in Ihrem Styleguide verwenden können, wenn er wächst. Beispielsweise:

"Elemente" ist ein sehr vager Begriff, der sich auf ein beliebiges HTML-Element beziehen kann, daher könnte ein besserer Name für diese Gruppe "Komponenten" oder "Module" sein. Dies sind immer noch allgemeine Begriffe, sind jedoch spezifischer in Bezug auf die Art der Elemente, die abgedeckt würden.
"Primary vs. Secondary" Buttons könnten Teil von "Base Elements" sein und der Farbaspekt könnte in eine "Color Palette" Kategorie fallen.

Darüber hinaus können Sie über eine Kategorie nachdenken, in der Sie allgemeinere Informationen zu Ihrem Styleguide hinzufügen können. Ein gutes Beispiel hierfür wäre ein Abschnitt "Anleitungen", in dem Sie beschreiben können, wie Sie zum Styleguide beitragen können, oder einen Abschnitt "Branding", in den Sie Richtlinien für Ihre Marke aufnehmen können, die beim Entwerfen und Implementieren Ihrer App berücksichtigt werden sollten.

In diesem Sinne würde das Diagramm wie folgt aussehen:

Sie können sehen, wie dieses Diagramm die Form einer Site Map annimmt, die Sie bei der Erstellung Ihres Living Style Guides grundsätzlich als Plan verwenden möchten.

Tauchen Sie jetzt in die Designs ein und skizzieren Sie Ihre eigene Sitemap, einschließlich so vieler Kategorien, wie Sie für die Zukunft für nützlich halten. Sie können Ideen von anderen Styleguides bekommen ( Styleguides.io/Beispiele ist eine großartige Ressource). Sobald Sie fertig sind, überprüfen Sie diese umfassendere Version und vergleichen Sie.

Erstellen von Seiten in einem Living Style Guide

Während der Großteil Ihrer LSG-Dokumentation aus speziellen Kommentaren stammt, die Sie dem Quellcode hinzufügen, können Sie auch Standalone-Seiten erstellen, auf denen Sie andere Arten von Inhalten hosten können, die nicht für den Code spezifisch sind. oder Pull Request Richtlinien). Dies bietet Ihnen den Vorteil, Ihre Dokumentation an einem Ort zu zentralisieren: Ihrem Anwendungsleitfaden für den Lebensstil.

Du könntest fast den Living Style Guide als "Spielregeln" deiner App ansehen. Innerhalb der "Regeln" sind alle Informationen enthalten, die benötigt werden, um das Spiel zu "spielen": Die Bausteine und die Regeln für das Erstellen und Erstellen neuer Blöcke. Einschließlich, wie andere Mitglieder Ihres Teams dazu beitragen können, es als lebendiges Dokument zu erhalten.

_Yas! _{Glaube es.} _{Sie können alle Ihre Dokumente an einem einzigen Ort konsolidieren!}

In diesem Sinne beginnen wir mit der Installation der Beispielanwendung, die wir für dieses Tutorial verwenden werden.

Installieren der Beispielanwendung

Der Installationsprozess hat 3 Schritte:

1. Installation des Knotens

Stellen Sie zuerst sicher, dass Sie haben Knoten Eingerichtet. Sie benötigen mindestens Version 6.

2. Installieren der App

Laden Sie dann diese Zip-Datei herunter: sgdd-tutorial.zip auf Ihren Desktop und entpacken Sie es . Dies ist wichtig, da ein anderer Ort die Installationsbefehle unterbricht.

Öffnen Sie dann das Terminal und geben Sie folgenden Befehl ein:

cd ~/Desktop/vintage-shop-sgdd-tutorial && npm install

Es dauert ein paar Sekunden, um die App und ihre Abhängigkeiten zu installieren.

3. Ausführen der App

Sobald die Installation abgeschlossen ist, geben Sie die folgenden Befehle ein:

npm run develop
In einem neuen Tab geben Sie ein: npm run document

Nun, lasst uns das aufschlüsseln:

npm run develop

Startet einen Server, auf dem die App unter folgender Adresse angezeigt wird: http://localhost: 8080. Sie werden im Terminal sehen:

Und im Browser:

npm run document

Erzeugt den Living Style Guide bei http://localhost: 8080 / styleguide. Sie können die Flagge hinzufügen -- -w Mit diesem Befehl können Sie nach Änderungen in Ihrem Code suchen und anschließend ein Update im Living Style Guide generieren:

npm run document -- -w

Wechseln Sie zum Browser, den Sie sehen sollten:

Der generierte Living Style Guide verwendet DokumentCSS Sehen wir uns an, wie das funktioniert.

Wie funktioniert DocumentCSS?

DocumentCSS ist ein statischer Site-Generator. Das heißt, es sucht nach speziell formatierten Kommentaren in Ihrem Code und erstellt eine statische Website. Diese Seite heißt "statisch", weil sie bis zu einem Befehl unverändert bleibt (in diesem Fall) Dokument ) wird erneut ausgeführt. Dieser Workflow eignet sich gut zum Erstellen eines Living Style Guides, da Änderungen an Ihren Stylesheets auch Änderungen an der statischen Site des Living Style Guides betreffen.

Um einen lebendigen Stil Guide zu erstellen, tut DocumentCSS Folgendes:

Liest die in der Konfiguration angegebenen Dateien durch (für dieses Tutorial wird es betrachtet) .less und .md Dateien)
Sucht nach Kommentaren, die spezielle "Tags" verwenden (wie @page , @stylesheet oder @styles .
Erzeugt HTML-Dateien und verbindet sie zum Erstellen der Website.

In diesem Sinne sollten wir uns kurz mit DocumentCSS beschäftigen, um eine neue Seite im LSG zu erstellen.

Eine Seite erstellen

Öffnen Sie zunächst die Beispielanwendung in Ihrem Code-Editor. Sie sollten die folgende Dateistruktur sehen:

Drill down in Src und finden base/markdown . Hier finden Sie Seiten, die bereits im Style Guide vorhanden sind. Erstellen Sie eine neue Markdown-Datei und nennen Sie sie "about" (mit der Erweiterung .md ). Ihre Dateistruktur sollte jetzt so aussehen:

Fügen Sie innerhalb dieser neuen Datei das Tag hinzu @page gefolgt von zwei Strings:

@page about about

Jetzt lasst uns das durchbrechen:

@page

Das Tag @page deklariert die Datei als Seite und teilt DocumentCSS mit, dass die Informationen in dieser Datei als eine Seite im Styleguide angezeigt werden sollen. Dies dient dazu, sie von Stylesheets, JavaScript oder anderen Dateitypen in Ihrer Dokumentation zu unterscheiden.

about

Dies ist der eindeutige Name für die Seite und wird als Referenz für andere Tags verwendet. Also halten Sie es kurz, klein und einfach, da es als URL für die Seite verwendet wird. In unserem Beispiel lautet die URL für unsere neue Seite: http://localhost: 8080 / styleguide / about.html

About

Dies ist der Titel der Seite, die für die Anzeige in der generierten Site verwendet wird. Hier können Sie mehrere Wörter mit Leerzeichen oder anderen Zeichen verwenden.

Um die neu erstellte Seite anzuzeigen, führen Sie erneut documentjs im Terminal aus (es sei denn, Sie haben nach Änderungen Ausschau gehalten), und gehen Sie dann zu http://localhost: 8080 / styleguide / about.html um die neue Seite anzuzeigen.

Der nächste Schritt besteht darin, Ihre Seite der Navigation hinzuzufügen. Fügen Sie dazu wie folgt eine zweite Zeile zu Ihrer Datei hinzu:

@page about About@parent index

Das Tag @parent ermöglicht es, einen Elternteil für Ihr Dokument anzugeben. In diesem Fall möchten wir, dass die "Über" -Seite unter dem Home-Bereich angezeigt wird. Jetzt können Sie die Dokumente erneut ausführen und sehen, dass die Seite unterhalb des Links "Willkommen" angezeigt wird:

Und wenn Sie auf den Link "Willkommen" klicken, gelangen Sie auf die Startseite:

Jetzt ist es gut, Inhalt mit Markdown oder HTML zu dieser Seite hinzuzufügen. Um die Übung zu beenden, fügen wir den folgenden Dummy-Inhalt hinzu:

@page about About@parent index## Hello World!This is the first page of my style guide. Here I can add any type of content that shouldn’t live with the code. Like who are the main contributors of the style guide or contact info.For example here's an animated gif inside of an `iframe`:

Und hier ist die Ausgabe:

`Dokumentieren eines Stylesheets in einem Living Style Guide`

Das Herzstück einer LSG ist die Möglichkeit, Ihre Dokumentation dort zu platzieren, wo sie hingehört: im Quellcode. Es ist gut möglich, dass Sie Ihren Code bereits dokumentieren. Dies ist eine großartige Gelegenheit, ihn auf die nächste Stufe zu heben, indem Sie einen Styleguide-Generator verwenden, der diese Kommentare in eine organisierte Site umwandelt was im Code getan wurde.

Du selbst aus der Zukunft, nachdem du die Dokumente gelesen hast, die du in der Vergangenheit geschrieben hast.

`Ein Stylesheet dokumentieren`

Die Dokumentation eines Stylesheets folgt einem ähnlichen Muster eine Seite dokumentieren , aber in diesem Fall wird die Dokumentation in einen Kommentar direkt neben dem Code (das ist die Schönheit!) gehen.

Um zu beginnen, öffne das Stylesheet: buttons-custom.less .

Fügen Sie das Tag innerhalb dieser Datei und innerhalb eines Kommentarblocks hinzu @stylesheet gefolgt von zwei Strings:

/**@stylesheet buttons.less Buttons*/

Beachten Sie, dass der Dokumentationskommentar mit beginnen muss /** für den Parser (in diesem Fall JSDoc ) um es zu erkennen.

Jetzt lasst uns das durchbrechen:

@stylesheet

Das Tag @stylesheet deklariert die Datei als Stylesheet und sagt es DokumentCSS dass die Informationen in dieser Datei im Styleguide angezeigt werden sollen. Dies dient dazu, es von anderen Arten von Dokumenten, wie Seiten, Komponenten und Modellen, zu unterscheiden ( Lesen Sie hier über die vollständige Liste der Dokumenttypen ).

buttons.less

Dies ist der eindeutige Name für das Stylesheet und wird als Referenz zu anderen Tags verwendet. Obwohl Sie jeden beliebigen Namenstyp verwenden können, empfehle ich, den Namen der Stylesheet-Datei zu verwenden, da dies dazu beiträgt, die Datei beim Verweisen auf die Dokumentation zu finden. Beachten Sie, dass sich dies auf die URL Ihres Dokuments auswirkt. In diesem Beispiel lautet die URL: http://localhost: 8080 / styleguide / buttons.less.html

Buttons

Ähnlich zu Erstellen einer Seite Dies ist der Titel des Stylesheets, das für die Anzeige in der generierten Site verwendet wird. Hier können Sie mehrere Wörter mit Leerzeichen oder anderen Zeichen verwenden.

Um die neu erstellte Seite anzuzeigen, führen Sie den folgenden Befehl aus, sofern Sie nicht nach Änderungen Ausschau halten):

documentjs

Und dann geh zu http://localhost: 8080 / styleguide / buttons.less.html um die neue Seite anzuzeigen.

Nun fügen wir dieses neue Dokument zu unserer Navigation hinzu. Dazu folgen wir der gleichen Konvention, die wir bei der Erstellung der Seite unter Verwendung der @parent Etikett:

/*** @stylesheet buttons.less Buttons* @parent styles.base*/

Beachten Sie, dass wir in diesem Fall hinzugefügt haben .base Diese Seite anzugeben sollte unter der Gruppe "Baseline" erscheinen, die in der Seitenleiste angezeigt wird (Sie können auch Gruppen in Ihrem Subnav erstellen! Wir werden das ein wenig genauer untersuchen).

Das erneute Ausführen der Dokumente und das Aktualisieren der Seite sollte folgendermaßen aussehen:

Jetzt zum fleischigen Teil! Mit unserer Seite können wir ein paar Dinge tun:

Wir können eine allgemeine Beschreibung für das Dokument hinzufügen
Wir können alle Arten von Inhalten sowohl mit Markdown als auch mit einfachem HTML hinzufügen
Und das Beste von allem, wir können Demos für unseren Code hinzufügen?

Fügen wir eine kurze Beschreibung und eine Demo für unsere Schaltflächen doc hinzu:

/*** @stylesheet buttons.less Buttons* @parent styles.base* @description* Global style definitions for all button elements.* @iframe src/base/bootstrap-custom/buttons/buttons-custom.html*/

Führen Sie die Dokumente erneut aus und?:

Wie Sie sehen können @iframe Mit dem Tag können Sie Ihrem Dokument einen iFrame mit einer Demo hinzufügen. Diese Demo ist wirklich nur eine einfache HTML-Datei mit einem Skript-Tag, das zur Laufzeit das CSS Ihrer App importiert.

Lass uns die Demo öffnen buttons-custom.html :

Und sehen Sie, wie der Code aussieht:

<script src="/node_modules/steal/steal.js" main="can/view/autorender/"><import "vintage-shop/styles.less";script> <a class="btn btn-default" href="#" role="button">Linka><button class="btn btn-default" type="submit">Buttonbutton><input class="btn btn-default" type="button" value="Input"><input class="btn btn-default" type="submit" value="Submit"><hr /><button type="button" class="btn btn-default">Defaultbutton><button type="button" class="btn btn-primary btn-checkout">Primarybutton><button type="button" class="btn btn-success">Successbutton><button type="button" class="btn btn-info">Infobutton><button type="button" class="btn btn-warning">Warningbutton><button type="button" class="btn btn-danger">Dangerbutton><button type="button" class="btn btn-link">Linkbutton>

Das einzige, was in dieser Datei benötigt wird, ist das Skript-Tag, das für jede Demo, die Sie in dieser App erstellen, identisch sein sollte. Der Rest des Codes ist das Markup mit den Stilen, die Sie in der Demo zeigen möchten.

Zusätzlich können Sie das Tag verwenden @demo um auch den Codeschnipsel anzuzeigen, der darin verwendet wird. So was:

/*** @stylesheet buttons.less Buttons* @parent styles.base** @description* Global style definitions for all button elements.* @demo src/base/bootstrap-custom/buttons/buttons-custom.html*/

Was wird so ausgegeben:

Demos Kredit geht an Bootstrap-Dokumente wo wir den Code abschnappen.

Jetzt, bevor Sie mit diesem Bananen gehen, gibt es ein paar mehr Leckereien, die Sie nutzen können:

Erstellen von Stilabschnitten
Stylesheet-Gruppen erstellen

`Erstellen von Stilabschnitten`

Um einen Stilabschnitt zu erstellen, können Sie das Tag verwenden @styles . Dieses Tag ist süß, weil es Ihnen ermöglicht, Ihr Stylesheet-Dokument in sinnvolle Brocken zu zerlegen, über die Sie sprechen und besser verstehen können.

In unserem Beispiel verfügen wir beispielsweise über Stile zum Definieren von Schaltflächen im Allgemeinen, unabhängig vom verwendeten Markup (entweder a



    
        
            
            ← Sollte das Web ein Universal Design System haben?            
            10 Überraschende Wege Chatbots revolutionieren E-Commerce →