Der folgende Beitrag wurde von Nick Berens verfasst, einem Senior Front-End-Entwickler bei wisnet.com. Nick und sein Team erstellen seit Jahren Websites über benutzerdefinierte Styleguides. Über die Jahre hat Nick ein Tool entwickelt und weiterentwickelt, das diesen Prozess unterstützt. Ich überlasse es Nick, sowohl die Philosophie als auch das Tool zu erklären.
Ich wette, Sie haben von Styleguides gehört. Vielleicht haben Sie schon von Style Guide Driven Development (SDD) gehört?
Ich bin Front-End-Entwickler bei wisnet.com, einer Agentur, die sich auf PHP- und WordPress-Entwicklung spezialisiert hat. Hier ist eine kurze Einführung in Styleguides und die Erfahrungen unseres Teams mit Style Guide Driven Development.
In den letzten 2 Jahren habe ich SDD mit einem von mir geschriebenen Tool namens Atomic Docs praktiziert, einem Generator für Front-End-Styleguides und einem Sass-Partial-Manager. Ich möchte Atomic Docs und einige seiner Funktionen vorstellen, die SDD zu einem einfachen und wesentlichen Bestandteil unseres Workflows gemacht haben.
Was ist ein Styleguide?
Bei wisnet arbeiten wir mit zwei Arten von Styleguides. Ein statischer Design-Styleguide und ein dynamischerer Front-End-Styleguide.
Design-Styleguides
Unsere Design-Styleguides sind statische Photoshop (PSD) -Dateien, die die globalen Designelemente eines Projekts katalogisieren. Sie dokumentieren die Farben, Schriftarten, Überschriften, Schaltflächenzustände, Linkzustände, Listen usw. eines Projekts.
Front-End-Styleguides
Unser Front-End-Styleguide, der von Atomic Docs generiert wird, bietet Dokumentation für den Code, der mit den Front-End-Komponenten eines Projekts verbunden ist. Stellen Sie sich die Dokumentationsseite für Bootstrap vor. Sie enthält Hinweise und Markup-Beispiele für jede seiner Komponenten, was die Referenzierung, das Verständnis und die Verwendung jeder Komponente erleichtert.
Lebende Styleguides
Ein lebender Styleguide ist ein System, das es ermöglicht, dass die Komponenten innerhalb des Styleguides synchron mit den Komponenten der Website bleiben, ohne den Code an beiden Stellen aktualisieren zu müssen!
Für große Projekte ist ein lebender Styleguide der Schlüssel für ein erfolgreiches System.
Was ist Style Guide Driven Development?
Zur Veranschaulichung werde ich kurz unseren Prozess bei wisnet skizzieren.
Es beginnt mit dem Design
Bei wisnet beginnt unser Styleguide-Prozess mit unseren Designern. Jedes Projekt, das sie übergeben, bringt zwei Ergebnisse mit sich. Eine traditionelle PSD-Kompression der vollständigen Seitenlayouts sowie ein Design-Styleguide, der die globalen Stile des Projekts dokumentiert.
Weiter zum Front-End
Sobald die PSD-Kompression und der Design-Styleguide fertig sind, werden sie an einen Front-End-Entwickler übergeben. Das Erste, was ich tue, ist, Atomic Docs zu öffnen und mit der Dokumentation der globalen Designelemente gemäß dem Design-Styleguide zu beginnen.
Nachdem die globalen Designelemente hinzugefügt wurden, öffne ich die PSD-Kompression, die das vollständige Design enthält. Da ich Brad Frosts Atomic Design-Prinzipien verwende, analysiere ich nun das Design und entscheide, welche Designelemente zusammenkommen, um die Atome, Moleküle, Organismen, Vorlagen und Seiten des Designs zu bilden. Die Organisation und Verwaltung von Komponenten auf diese Weise ist dort, wo Atomic Docs wirklich hilfreich ist.
Sobald alle Komponenten in Atomic Docs erstellt, kategorisiert und dokumentiert sind, ist es einfach eine Frage der Verwendung der Komponenten wie Legosteine, um die Seiten und Ansichten zu erstellen.
Das Back-End
Wenn es sich bei dem Projekt um eine Anwendung handelt, übergebe ich die statischen Ansichten zusammen mit dem Atomic Docs Styleguide. Mit dem Styleguide als Referenz ist es für die Backend-Entwickler einfach, Anpassungen am Front-End vorzunehmen, ohne ihren Workflow unterbrechen zu müssen, indem sie ihn wieder an einen Front-End-Entwickler zurückgeben.
Wie Sie vielleicht vermuten, ist der Entwicklungsprozess nie *ganz* so linear (es kann immer noch viel Hin und Her zwischen den Teams geben), aber die Verwendung von Styleguides bietet eine gemeinsame Designsprache, die die Konsistenz von Design und Code über die gesamte Lebensdauer eines Projekts hinweg durchsetzt.
Was sind die Vorteile von SDD?
Durch das Erstellen von Komponenten außerhalb jedes Kontexts erhalten Sie Code, der modular und frei ist, um ihn in Ihrer Website oder Anwendung zu verschieben
Wir entwerfen keine Seiten, wir entwerfen Komponentensysteme.
Stephen Hays Zitat steht im Mittelpunkt von SDD.
Wir bauen keinen Button mehr, der rot ist, wenn er sich im Kontext einer Seitenleiste befindet. Wir bauen jetzt nur noch einen roten Button, der rot sein wird, egal ob er sich in einer Seitenleiste, einem Footer oder einem Header befindet.
Wenn Sie ohne Kontext bauen, ist der Nebeneffekt eine Front-End-Codebasis, die weitaus skalierbarer, modularer und wartungsfreundlicher ist.
Machen der Komponenten zugänglicher für weniger Front-End-affine Backend-Entwickler und Designer
Styleguides haben unsere Designer und Junior-Entwickler dazu ermutigt, Seiten und Ansichten schnell zu erstellen, ohne ein tiefes Verständnis von HTML/CSS/JS zu haben. Und da jede Komponente isoliert ist, ist es einfacher, den Code zu verstehen, der sie erstellt hat.
Jedes Projekt, das ich abschließe, hat eine Bootstrap-ähnliche Dokumentation, die das relevante HTML/CSS für jede Komponente zeigt
Unabhängig von der Größe hat jedes Projekt, das unser Team abschließt, eine vollständige Dokumentation seines Front-End-Designsystems. Das macht jedes Projekt weitaus wartungsfreundlicher. Es ist besonders nützlich für die Organisationen, mit denen wir zusammengearbeitet haben und die interne Entwicklungsteams haben. Es hat diesen Gruppen erleichtert, ihre Projekte zu ändern und zu skalieren, und war wertvoll.
Durchsetzung der Markenintegrität
Da der Styleguide die Farb- und Schriftartendefinitionen des Projekts zusammen mit Logos und anderen Grafikassets enthält, kann er als Design-Wahrheitsquelle betrachtet werden.
Über Atomic Docs
Atomic Docs hat zwei Hauptfunktionen.
SCSS Partial Manager
Die Möglichkeit, mein CSS in kleine Partial-Dateien aufzuteilen, ist eine meiner Lieblingsfunktionen von Sass. Die Verwaltung all dieser Partial-Dateien jedoch nicht.
Hier ist ein Screenshot einer Moleküle-Kategorie und der Stammdatei `molecules.scss`.
Diese Struktur zu erstellen ist **wunderbar** für die Organisation und die allgemeine Entwickler-Gesundheit. Aber mit wachsendem Projekt wird die Erstellung und Verwaltung der Partial-Dateien zu einem Painpoint in meinem Workflow.
Atomic Docs bietet eine GUI zur Erstellung und Verwaltung dieser Partial-Dateien sowie zum Schreiben des Strings ` @import my-component` in die entsprechende Stamm-.scss-Datei. Über diese Oberfläche können Sie auch Dateien umbenennen, in andere Kategorien verschieben und löschen.
Sie denken vielleicht, dass ich super faul bin und das Erstellen von Partial-Dateien wirklich keine große Sache ist, aber es ist wirklich mein Lieblingsteil von Atomic Docs.
Der (generierte) Styleguide
Vielleicht ist der größte Vorteil der Verwendung von Atomic Docs, wie einfach es ist, den Styleguide zum Laufen zu bringen.
- Keine komplexen Konfigurationsdateien
- Keine Notwendigkeit, redundante Markup-Kommentare zu Ihren CSS-Dateien hinzuzufügen
- Benennen Sie Ihre Komponenten und Kategorien, wie Sie möchten
- Nicht voreingenommen über den von Ihnen verwendeten Präprozessor. Sie können Grunt, Gulp, Code Kit, Prepros oder was auch immer verwenden.
Dies soll die Projekte, die komplexer sind, nicht schmälern. Diese Komplexität ermöglicht ihnen einige wirklich fortgeschrittene Funktionen. Ich wollte nur eine Lösung, die etwas einfacher ist und unser Team mit wenig Reibung zum Laufen bringen kann.
Atomic Docs als lebenden Styleguide verwenden
Atomic Docs kann als lebender Styleguide konfiguriert werden. Wenn sich die Datei `atomic-head.php` im Stammverzeichnis Ihres Projekts befindet, wird Atomic Docs sie in den `<head>`-Abschnitt aufnehmen. Wenn Sie beispielsweise mit einer einfachen PHP-App arbeiten würden, könnten Sie in `atomic-head.php` `<?php require_once(my-path/db.php); ?>` einfügen, um die Datenbank mit Atomic Docs zu verbinden, sowie `<?php require_once(my-path/functions.php); ?>`, um die Funktionen Ihrer App zu teilen.
Nun können Sie mit den Daten und Funktionen Ihrer App in den von Ihnen erstellten Komponenten arbeiten. Dann müssen Sie nur noch `<?php include(components/modules/my-component.php); ?>` in Ihrer Anwendung einfügen. Da diese Komponente bereits in Atomic Docs enthalten ist, wird jede Änderung, die Sie in `components/modules/my-component.php` vornehmen, sowohl im Styleguide als auch überall dort, wo Sie die Komponente in Ihrer Anwendung einfügen, widergespiegelt.
Weitere Ressourcen
Atomic Docs ist großartig für unseren Workflow und unseren Entwicklungsstack bei wisnet. Wenn es für Sie nicht passt, gibt es viele großartige Lösungen.
- Styleguides.io hat eine wunderbare Sammlung von Artikeln, Büchern, Tools und Vorträgen, die Ihnen helfen, die richtige Entscheidung für Sie und Ihr Team zu treffen.
- Für einen tieferen Einblick in Styleguides lesen Sie diesen großartigen Artikel auf Medium.
Fazit
Nach zwei Jahren hat sich Style Guide Driven Development als wertvolle Ergänzung unseres Workflows bei wisnet erwiesen. Ob Sie Atomic Docs oder eines der anderen großartigen Tools verwenden, ich denke, Sie werden feststellen, dass SDD dazu beiträgt, Designkonsistenz und Skalierbarkeit für all Ihre Projekte zu gewährleisten.
Dies ist wirklich ein großartiges Werkzeug, das mir geholfen hat, über den Code nachzudenken, den ich schreibe, und wie er für sich allein in jedem Kontext funktionieren kann, anstatt Elemente mit einem bestimmten Zweck zu codieren. Die kleine zusätzliche Zeit für die Erstellung von Atomen und Molekülen beschleunigt die Entwicklung im weiteren Verlauf. Eine visuelle Benutzeroberfläche zu haben, um all Ihre Elemente für sich genommen zu betrachten, ist auch großartig (besonders für Farben und Schaltflächen). Danke, dass du großartig bist, Nick!
Wie erstellen Sie ein Front-End ohne Back-End? Wenn Sie sagen: „Ich werde die statischen Ansichten übergeben … damit Backend-Entwickler Anpassungen am Front-End vornehmen können“, schreiben Ihre Backend-Entwickler dann die Front-End-Ajax- und Formularübermittlungen?
Das hängt vom Projekt ab. Die Grenze zwischen Front-End und Back-End wird ziemlich verschwommen.
Wäre ein JSX-Markup-Abschnitt auch für React-Leute nützlich? Nicht sicher, ich werfe das nur mal so in den Raum…
Es ist eine so gute Idee und Bequemlichkeit für Ihr Team, einen lebenden Styleguide zu haben. Gibt es noch andere ähnliche Lösungen?
Habe gerade Atomic Docs heruntergeladen, kann es aber auf einer frischen Kopie von Mamp nicht zum Laufen bringen. Vielleicht einige Berechtigungen auf den Ordnern, in die es schreiben und die vorhandenen Dateien ändern muss?
Tut mir leid, das zu hören. Sie können Ihr Problem gerne auf GitHub posten.
https://github.com/nickberens360/atomic-docs
Habe gerade Mamp auf meinem Mac installiert und wollte Atomic Docs herunterladen. Welche Probleme sind bei Ihnen aufgetreten und wurden sie behoben?
Ich habe gerade Mamp auf meinem MacBook installiert und Atomic Docs funktioniert bei mir einwandfrei.
Ich wollte nur bestätigen, dass es bei mir mit Mamp auch einwandfrei funktioniert hat :)
Habe dieses Paket in Verbindung mit WordPress ausprobiert, dank des Unterabschnitts der Online-Dokumentation, den Sie bereitstellen.
Ich muss sagen, es ist eine großartige, sinnvolle Methode, um Prinzipien des atomaren Designs in einem lebenden Styleguide-System wie diesem zu erlernen. Tolle Arbeit :)
Nebenbei bemerkt, frage ich mich, ob der „JS“-Ordner ein Hinweis auf eine bevorstehende JS-Snippet-Funktion ist?
Wenn das passiert, muss ich zugeben, dass ich nicht wüsste, wie ich solche Designprinzipien auf eine JS-Architektur anwenden sollte. (include() / @import-Äquivalent.) vielleicht mit Modul-Loadern à la Browserify. Mein Wissen reicht in diesem Bereich nicht aus.
Außerdem würde ich mir wünschen, dass ich Arbeitsverzeichnisse für AtomicsDocs festlegen könnte. Ich vermeide es, meinen Theme-Ordner mit Quellcodedateien zu überladen, daher wäre die Möglichkeit, Atomic-Docs überall in einer WordPress-Umgebung zu platzieren, meiner Meinung nach ein großer Vorteil.
Der JS-Ordner ist im Moment nur zur Bequemlichkeit vorhanden. Aber ja, ich habe darüber nachgedacht, die Option hinzuzufügen, eine JS-Datei zu erstellen, wenn eine neue Komponente hinzugefügt wird. Die Tabs, die den Code dokumentieren, wären dann „Markup | Scss | Js“. Fast jedes Build-Tool (Grunt, Gulp, Webpack usw.) kann die Verkettung der JS-Partials verarbeiten. Ich benutze gulp-concat dafür.
Wir refaktorieren den Code derzeit auch, damit Sie das Arbeitsverzeichnis festlegen können. Danke für das Feedback!
Wirklich cool :) Kann es kaum erwarten!
Ich denke über einen Anwendungsfall nach: eine gemeinsame „Designbasis“ für WP Multisites / Themes (während spezifische Eigenheiten beibehalten werden), indem sie in einem übergeordneten Ordner von Themes platziert wird.
Oder man könnte es als persönliches Repository für gemeinsame Muster-Snippets mit der heiligen Dreifaltigkeit HTML/CSS/JS nutzen :)
Was JS angeht, dachte ich an die Verwendung eines klassischen, serialisierten Verkettungs-Workflows, wie Sie ihn vorschlagen, aber ich befürchte, dass dies nicht so mächtig sein wird wie die Verschachtelungslogik von PHP / SCSS.
Das gilt, wenn man strikt der Logik folgt: Atom > Moleküle > Organismen und dem DRY-Prinzip. (Wiederverwendung von Atomen / Molekülen in verschiedenen Kontexten)
Entschuldigen Sie, dass ich frage, ohne atomicdocs.io genauer untersucht zu haben, aber was sind die Unterschiede zu Pattern Lab? Auf den ersten Blick schätze ich die zugänglichere Benutzeroberfläche, aber könnten Sie auf einige der anderen Unterschiede eingehen? Vielen Dank!
Hallo Brian, ich habe wirklich keine Erfahrung mit Pattern Lab, außer dass ich die Dokumentation durchgeblättert habe. Ich wäre daran interessiert, Ihre Gedanken zu hören, wenn Sie beide ausprobieren.
Ist es möglich, JavaScript in einem Modul mit Atomic Docs zu verwenden?