Component and Style Guide Driven Development of Wordpress Themes for Developers

When can they help? But there are certain situations where over time even if adoption takes some time you can get a good return on your investment

Style guides shine when you need to coordinate development between lots of people and roles, or over time different people will be working on the site

Documentation is an essential part of successful projects, but often absent for the front ends of our websites. If you weren’t there when the thing was designed, then you have to reverse engineer the interface to find out how to do things or track down someone who may or may not still be available

Style guides are also amazing for facilitating user testing. They can be tested against directly, or used as an up to date reference for testers who are testing the finished product

KSS Node KSS stands for Knyle StyleSheets it’s a documentation format for CSS (a way to include structured information inside CSS comments that can then be parsed and used to create documentation).

KSS node uses this documentation format and some conventions to parse the information it needs for components out of comments included in the CSS.

It’s quite actively maintained and because it’s powered by inline comments it’s got a very low barrier to entry and maintenance. Anyone who edits your CSS will see the comments with the documentation that gets turned into your style guide and hopefully be able to update it.

It also supports twig templates, which means if you want to re-use templates between your style guide and your WordPress theme then this is possible with a bit of work as there is an implementation of twig for php and javascript, which KSS node is written using.

Fractal Fractal is a project from a company called Clearleft a very well known and regarded design consultancy that have been around for a long time and, coincidentally, are based in Brighton.

With fractal you specify your configuration with separate configuration files rather than inline CSS comments. Which gives you a bit more flexibility in terms of the content you can add and I feel make it a bit more easily extensible.

Unfortunately development has been stalled for a while, I believe it was mostly the work of a couple of developers who due to changes in situation could no longer spend much time on the project and this alongside a push to rearchitect the project into a v2 caused development to languish.

However, luckily, this was recently brought to the attention of wider audiences, I believe I noticed an increase in attention after a smashing magazine post by Rachel Andrews who was documenting her dev process with fractal which I showed a snapshot of earlier in the Perch example. And now it looks like there have been a lot of people offering support to continue the development of the tool as noted in recent updates to their README on github.

So I feel a lot more comfortable recommending it’s use now.

THE…

the default theme for fractal looks a lot more polished than KSS node, given it’s origins in a design consultancy this isn’t surprising

however I think the initial configuration and learning curve is steeper than with KSS node, and it feels like the tool is maybe more complicated in it’s implementation than it needs to be. Which I think is one of the things the rearchitect to v2 was aiming to work on, however although there are now offers from possible maintainers it’s not clear to me that work on a v2 will continue, I think we are more likely to see incremental work on v1

By default it uses mustache for templates - it seems like it might have support for twig but I’m not sure how feature complete and ready for use that is. There are implementations of mustache for PHP so you can with some work look to re-use templates between your styleguide and your website to reduce duplication

I’d recommend looking at and experimenting with both tools if you can afford it and see which suits you better. But if you can only look at one, try Fractal because there seems to me to be more and better documentation available and it gets you closer to something useful out of the box.

Both tools have good explanations of the initial config you need to get started and generate your first style guide.

Once you’ve worked out what you’re going to build it with you need to decide…

Where will you create it? You might initially decide to spin up a separate repository for it, however I would recommend you start by just keeping the configuration files for your style guide in a sub folder of your theme repository. Seems like a small decision, but splitting things prematurely can throw up problems that slow you down and you need to be e ﬃ cient if you’re trying this for the first time so you don’t end up having to stop your work on it to focus on the actual work of creating your website.

Where it might be useful to keep it in a separate repository would be if you were going to supply your styles and js via a plugin or NPM module rather than a theme so they can be more easily re-used between different websites.

Then it’s good to think about…

Markup is defined once in templates that both your theme and styleguide use The style guide build tools already use template languages internally, so it’s possible to create your component templates so that they can be re-used between the style guide and your wordpress theme

You need to create an API which in practice would just mean a function that you use for resolving the location of templates and rendering them with the supplied contextual data.

The gov.uk design system is a good example of a location that this is used, and for big projects that are maintained for a long time I think this is really essential. Though while using this method you will likely still have places where the HTML is written manually.

Besides re-use another way this helps is it keeps the output consistent. Someone isn’t able to leave out attributes or elements they think aren’t needed which might not have a visible impact for them but affect the accessibility of the component, or to swap the type of elements used in such a way that the accessibility of the component is impacted or how it displays on certain devices is changed.

Because this isn’t out of the box with any of the tools and lots of people don’t have experience with templating engines in wordpress, it might be worth skipping this to start with, and just ensuring that within wordpress you are limiting the amount of times you are repeating markup by encapsulating the html for your components in php functions when it needs to be re-used in several places.

NEXT…

So this is a little simplified flow chart of the different steps involved in the development process when developing with a style guide. It reads from top to bottom (DRAKON format) and the lines that diverge from the main line are things that can happen in parallel.

The key thing for me is that when you’re developing against a style guide it becomes easier to decouple the work on the front end from the integration work into wordpress.

You can quickly prototype and test designs, and because you then re-use the css and js you created for your style guide and static designs in wordpress (and also templates if you’re re-using templates between the styleguide and your wordpress theme) you aren’t throwing away work.

And the style guide serves as a place to put documentation that is available throughout the development process, where as normally documentation is a step at the end of the project.

I also feel like a lot of development processes tend to skip creating static versions of designs and go straight to creating in wordpress, I think this is a mistake because developing in wordpress is relatively expensive compared to working in static html that you can quickly deploy with something like netlify.

SO…

Thank you for listening! • Slides will be available online, I'll tweet a link to them and any more resources I have from @socialpoetry with the conference hash tag • You can grab me anytime if you want to talk about this more or get my contact details I hope if you’ve heard about style guides and pattern libraries before that this has given you some helpful information to help you break the seal and have a go at using them on a project. Or if you’ve never heard of them before that it’s given you a decent introduction.

I think for wordpress themes, where we have a lot that are sold as generic templates, supplying a style guide alongside your theme could be very useful. And in teams style guides provide great benefits in lots of areas and once you’re comfortable using them they become a default on almost every project.

—

other bits that are semi-related

complements compiling your wordpress content as static website using node js or a tool like gatsbyjs

how does gutenberg change things? Not massively, as I think gutenberg is just outputting static html so your patterns would still apply, might want to have a separate styleguide of gutenberg components though to manage the styles for the input components. Stuff like react-storybook is good to look at in this arena.