Using Style Guides for modular WordCamp designs

Yesterday we published an update on make.wordpress.org about our new WordCamp theme called CampSite 2017. That’s a theme we are building within our WCEU Design team and is now ready for a review. In today’s article, we will show you how to work with style guides which you can use to style your WordCamp website.

When designing WordCamp websites, we have a choice of available themes and custom CSS to work with. We can do some basic visual customisation within the Customiser (colours, backgrounds, etc.) if the theme supports it — but we need to use custom CSS to completely restyle the website.

It’s important to note that due to the technical restrictions of WordCamp sites we can’t modify the theme’s HTML or JS, so it’s only natural to choose the theme that fits our needs best — either with widget areas or a flexible layout foundation. Besides the theme’s HTML base, shortcodes are also available for adding new functionality, either handling ticketing or displaying attendees and speakers. Shortcodes also output HTML code that we have no control over, so it can be tricky to account for all use–cases.

If you were to design (or test) directly in the browser on a staging environment, you would have to duplicate the WordCamp website functionality on your development server or locally — probably by using Varying Vagrant Vagrants (VVV). While this is a great way to get you started it’s not a quick or easy way to setup the theme with all required functionality locally or on a staging server. Especially if you are a front–end developer or a designer who writes HTML/CSS.

Components and Style Guides

We are working on documenting patterns in the form of a style guide — from available colours and fonts to different modules and widgets which will empower more people to see the inner workings of a theme design.

WordCamp Europe 2017 Style guide screenshots
WordCamp Europe 2017 Style Guide

The style guide is generated directly from the CSS (or SCSS in our case) by using Knyle Style Sheets (KSS) methodology. Markup examples inside our CSS are documented manually, but they enable us to style things quickly and offer live preview while writing CSS.

To keep the CSS readable, we opted to use codeguide.co standards for developing sustainable CSS. By utilising Inverted Triangle CSS methodology (ITCSS) by Harry Roberts, we also ensure that our CSS architecture remains scalable and maintainable. This will empower designers and developers to use our basic styles and build their components on top of them.

Even if you don’t wish to base your code on top of ours, you can still use our code examples from the KSS syntax and set up a build process that works best for you. The KSS specification has also been implemented in Python, Node.js, PHP and Java.

Code examples in our style guide have been inputted manually to keep things simple. If the code on the shortcode for attendees, for example, changes it should be updated manually in the style guide as well. Other blocks (comments, posts, branding, etc.) are based on the WordCamp Base Redux theme which is our theme of choice for WordCamp Europe (until we’re able to release the new CampSite 2017 default theme). When the new and improved WordCamp theme sees the light of day — we’ll promptly update the style guide markup to reflect these changes.

CSS code and a generated component in the style guide
CSS code and a generated component in the style guide

One of the downsides though is the mobile/desktop menu switchers which work by adjusting the HTML classes via JavaScript. To simulate that we should replicate that JavaScript snippet in the style guide template or create another component showcase specifically for the mobile menu.

Inspiration From the Community

The style guide we’re working on will be released open source — available to all, but would not be bundled with the WordCamp theme itself. It will be available to use in conjunction with the theme or as a place to see all the building blocks of the WordCamp website.

Blank WordCamp style guide screenshots: form elements and heading styles
Form elements and heading styles examples

Since our style guide documentation is generated automatically with the help of KSS’s machine parsable syntax — we are hoping that more people will get on on board using this technique and share their design resources for the benefit of the community.

Wouldn’t it be great if you could explore a WordCamp website design in layers as opposed to viewing source and inspecting elements in the browser? With the help of the style guide and modular CSS you can pinpoint the exact styles for one of our modules such as Ticket call–to–action and replicate it on your WordCamp site. We are excited to see where that road leads.

Getting Started

Our current style guide version is created automatically with the help of KSS node and Gulp. We use various Gulp plugins to compile SCSS, auto prefix and minify CSS. Images are also optimised — which are then uploaded to the WordPress media library. Finally, KSS node is responsible for generating the style guide out of CSS comments. To keep the styling process as efficient as possible we use browser sync plugin auto refreshes the style guide after each SCSS change.

Our WordCamp Europe 2017 style guide follows a modular approach so each component is saved as a single *.scss file. We also utilise the Modular scale plugin, Susy for grids and Bourbon, a simple and lightweight mixin library.

To get you started, we have prepared a blank WordCamp style guide — download the style guide GitHub repository (or clone it) and follow instructions to setup everything on your machine. If you want to change how the style guide looks, you can change the _styleguide.scss or even the style guide template styleguide-template/index.html.

To update the welcome text and style guide front page, modify the styleguide.md. All settings SCSS files (colours, typography, referenced background images etc.) are prefixed with _settings. That way you can change the colour scheme or typography options in one place and update the whole style guide at once — no need to go over each component by hand. Feel free to add/remove components you need. Once you are done, create a live refresh hook on GitHub and link directly to the /build/style.css from your WordCamp site. If you need inspiration — check WordCamp Europe 2017 style guide or WordCamp Europe 2018 style guide on GitHub.

Share your repository online and show your style guide to the community.

One Reply to “Using Style Guides for modular WordCamp designs”

Leave a Reply

Your email address will not be published. Required fields are marked *