Embracing a living style guide for streamlined development is becoming increasingly popular for its many benefits, including better code maintainability and design consistency. Ever pondered how to craft one? Wondering what to include and where to begin? In this tutorial, I’ll guide you through the nuances of generating an active style guide using DocumentCSS.
The Allure of Living Style Guides
Similar to traditional style guides, living style guides dictate stylistic standards for application design. Where classic style guides ensure brand integrity, their living counterparts aim for uniformity in application design and facilitate real-time guidance. What sets them apart is their direct linkage to the source code, enabling dynamic updates to the guide parallel to application development changes.
The revelation of employing your application’s source code to fashion your style guide can be quite astonishing.
Examining the shared traits of living style guides reveals their structure:
- An inventory of documented elements
- Detailed, lean documentation with code fragments and interactive UI presentations
Example from Lonely Planet’s Style Guide
Example from Sales Force’s Style Guide
An integral component of living style guides is the automation potential afforded by style guide generators. These tools ingest your source code to automatically populate large segments of your guide’s documentation and track code modifications, ensuring your guide remains up-to-date.
An Array of Style Guide Generators
A plethora of style guide generators are available, tailored to different coding languages and project structures. Here are several resources to explore your options:
- A Comprehensive Review of Living Style Guide Tools by Robert Haritonov, published by Smashing Magazine
- Compilation of Pattern Library Generators by David Hund on GitHub
- Roundup of Style Guide Generators by Susan Robertson on A List Apart
- Catalog of Style Guide Tools on Website Style Guide Resources
This walkthrough will illustrate the use of DocumentCSS, an open-source tool by Bitovi, for creating your guide. DocumentCSS is compatible with CSS and its preprocessors like Less and SASS, and it’s extendable to documenting JavaScript using DocumentJS, though that isn’t covered here.
Devising Your Style Guide
The first stride in formulating a living style guide is detailed planning. Consider the key UI elements that persist throughout the design, then tote these considerations forward to build the schematic of your guide.
Mockups from Vintage Shop
Start by mapping the larger design modules, such as navigation components, and gradually detail the stylizations that you regularly employ. Compile these into a diagram that acts as your style guide blueprint.
Further dissecting these modules allows for refined categorization within your style guide. Ponder about sections like “Components” and “Base Elements,” and consider adding a “Guides” or “Branding” category for overarching brand guidance.
Employ a site map-like structure in your planning. Solidify these categories by examining other style guides for inspiration.
Building Pages within Your Living Style Guide
Your living style guide should be seen as a point of reference, consolidating documentation for your application’s code and design protocols. It should outline the “rules of the game,” from the foundational building blocks to collaboration and maintenance guidelines. This unification of documentation ensures a cohesive and maintainable codebase.
Yes, it’s true, all documentation housed elegantly in one place.
Getting the Sample Application Up and Running
Follow these steps to install the sample application:
- Ensure you have Node installed (minimum version 6).
- Download sgdd-tutorial.zip to your desktop and extract it. Open your terminal and execute the given command to install the application.
-
To start the app, use the command:
npm run developThis will launch a server allowing you to view your running app at http://localhost:8080.
- Simultaneously, use the command
npm run documentto generate the living style guide, which can be viewed at http://localhost:8080/styleguide.
Understanding DocumentCSS’s Mechanism
DocumentCSS operates by parsing source code comments using specific tags and transforming them into a static website, a living style guide. File changes trigger updates to the guide’s content accordingly.
Creating a New Page
Dive into the existing file structure and add a markdown file named “about.” Then, use the @page tag to classify the contents as a style guide page. Give your page a unique name and a descriptive title for display. Remember to update the living style guide with content relevant to your design, including contributing guidelines or brand rules.
Documenting Stylesheets for Your Living Style Guide
Embedded documentation in your source code, processed through style guide generators, turns annotations into structured and informative documentation. Annotate stylesheets, with tags like @stylesheet and @iframe, to add demonstrations or general information directly connected to your styles.
Refining Style Sections and Groupings
Use the @styles tag to split your stylesheet documentation into comprehensible, linkable sections. Additionally, harness the @group tag for building out navigational groupings in the style guide’s sidebar. Adjust these groupings to truly reflect your application’s style architecture.
Concluding Thoughts
Living style guides are a powerful avenue for fostering a unified and consistent UI. Practicing Style Guide Driven Development, as well as modular design principles, amplifies their benefits. If you’ve followed this tutorial, you should now have a functioning living style guide and an insightful strategy for structuring future guides.
You, adeptly crafting living style guides!
