Let’s talk about FrontEnd Styleguides! With CTO.

Please mind this is the very first edition of the article. If there will be an interest and feedback, it will be augmented with images and diagrams.

Since ~2010 there have been written tons of interesting and influential materials about creating, maintaining and developing FrontEnd Styleguides.

I recall great articles along with the even greater books (only read Atomic Design, but I hope others are awesome as well!).

To name a few (you can find all of them here):

And to the most recent works:

The common greatness of these articles, success stories and tutorials is that they tell how to create and maintain Styleguides. Some of them suggest different approaches for the Components Library developing, another describe the reason and purpose, that puts it so clear and obvious!… 
For the developers.

Working as a team lead I used to dispute with managers and CTO many times, whether we need that or this to accomplish this or that. I discovered that level of understanding matters. This subtle thing, that alters the attitude.

Simply put — despite the immutable awesomeness of the topic — it won’t sell itself. It has to be sold.

So when I found myself cultivating the atmosphere of FrontEnd Styleguides in the new company (pun not intended) without asking anyone’s permission, and the questions began to rise, I realized that moment had come.

I will finally explain “how and why” all this guides work

The following article content is the adapted presentation 
of the FrontEnd Styleguides principles, elaborated for CTO. 
Most parts left unchanged, so don’t mind the thesis narration.


  • What is a library
  • Styleguides
  • Living Styleguides
  • Design Guides
  • Why is this important?

[Components] Library

Library is currently 2 things under one roof:

  1. HTML + CSS Components (in our case React + SASS)
  2. Components’ documentation — Living Styleguides


Components is an interchangeable part -
 depending on the chosen development stack — both Frontend and Backend (in out case React + NodeJS)

React can be replaced with the Angular, Handlebars, Dust etc.
NodeJS can be replaced with Ruby, PHP, Java etc.


In general the definition of the Styleguide is:

[Styleguide is] … a set of standards for the writing and design of documents, either for general use or for a specific publication, organization, or field

How this can be translated to Web Development language?

[Styleguide is] the depiction of variety of elements that happen to build up the pages and interact with each other implicitly or explicitly

Or simply put:

Visual documentation of the current codebase

Styleguide evolution

If you read carefully through the stories of establishing styleguides policy, you may find at least one failed attempt preceding the successful path. 
(I’ve been there too)

There are different stages of Styleguides evolution:

Static: PDF, PSD or Sketch files

  • static images or image-like documents
  • manually updated by designers
  • never represent all elements
  • may contain obsolete and prototype elements

Semi-static: pieces of static markup including HTML, CSS, sometimes JS

  • require maintaining along with codebase updates
  • may contain prototypes, something that is to be implemented
  • one can observe the resulting code
  • may represent samples in dynamic

Dynamic or Living: representation of code, that is being used

  • depends on the design only
  • always contains topical samples
  • may provide all sorts of integration information

Problem with the Static and Semi-static options

Achilles and the tortoise paradox

Image source: Grandjean, Martin (2014)

Here, developers are struggling with design updates as much 
as Achilles trying to get the tortoise.

That makes Living Styleguides
the obvious and most natural way to deal with the visual documentation.

This is how “A List Apartdefines them:

Styleguide is a living document of code,
which details all the various elements and coded modules
of your site or application

Let’s take a look at some real-life examples:

Design guides

Design Guides is a slightly different thing,
that usually co-exists with the FrontEnd Styleguides.

Design Guides may consist of:

  • visual language
  • design patterns
  • user empathy patterns
  • emotional language
  • user interaction patterns
  • and more

Practically speaking

Design Guides is about How to create,
whereas FrontEnd Styleguides is more about How to use.

Combination of Design Guides and FrontEnd Styleguides
results in …

Design System

Design System is a complex and powerful UI Development Platform.
It is a solid framework for the variety of interested developers.

That said, any third-party team can make use of it
without any help from the core team.

Design Systems examples:

Not to mention Google Material Design.

But there’s more about Design Systems!*

If you add Management and Marketing
you’ll get… The Product

*It is important to mention that it is great to know about Design Driven Product development and UX Strategy, but it is way too complex to cover right away.

Why it is important?

Development perspective

  • Easier development
  • Convenient debugging
  • Handy prototyping
  • Faster development
  • Convenient and easier QA
  • Enhanced workflow — think components not pages
  • Smaller codebase — better performance
  • Smooth newbies’ on-boarding process

Product perspective

  • Better communication between departments
  • Increased maintainability
  • Easier A/B testing setup
  • Scalability (themes, branches and agents)
  • Consistent design throughout the site
  • Happier users — > Better income

Cons that actually are Pros

  1. The System does not come out of the blue.
    It requires some time upfront to establish one.
    However afterwards the time for updates and refactoring 
    is considerably less
  2. The System is how Product functions and evolves.
    Teams from different departments should follow one lead.
    It means some time and skills are required to make this happen. 
    But what happens next — the whole Company speaks one language.

When the star begins to shine

There’s a possibility to improve the workflow even further…

Imagine a Service providing assets for both Designers, UX and Frontend developers. The Service is the one and only source of truth.
Designers get the SVGs, Frontenders get the code.

Example of such service (still work in progress) — Protein.

Though we can’t build a tool like that from scratch, there’s still a room for some improvements in a design delivery workflow. To achieve this we have to integrate Git into the Sketch — Zeplin pipeline.

Let’s recap (TL;DR)

  • Library is the Components AND Living Styleguide
  • Living Styleguides is the visual representation of the Components
  • It prescribes “what components to use and how to apply them”
  • Design Guides is about “how to create”
  • Design System is a powerful development platform
  • Add management and marketing and you’ll get a Product
  • To establish the System some time required upfront

And finally:

  • Library is an artifact of the Design System
  • It serves the Product and solves many development problems

Usually it takes 2–3 days to prepare a sturdy presentation, 
but for this one I only had 2–3 hours.

In case you wonder how it worked — it worked out just fine. 
I wish I had more time though.

It seems that the issue I’m trying to raise here is not something unique. 
In fact, I think it is pretty common. And it is the reason I’m sharing this.

Hope this helps you and your team.
Spread the word!
May the Styleguides be with you.

Like what you read? Give Evgeny a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.