Building Component-Based Style Guides and Documentation

Julien Melissas

 

Syntax Conference 2016

Hi! I'm Julien 🤓

Twitter: @JulienMelissas

Technical Director at Craftpeak

I like...

  • Dogs
  • Motorcycling
  • Music
  • Cooking
  • Other Stuff

Dina

Wilbur

Most days I do...

  • WordPress Development: on the roots.io team and build custom themes/websites/web applications all day
  • JS Development: Experience with React, Ember, Angular
  • UX/UI Consultation: building front end style guides and documentation for teams building new or redoing existing Web Applications

I'm not an expert.

(is anyone?)

"Lets build a

Web Application"

🛠

How we used to do it:

  1. Business requirements
  2. Wireframes
  3. Full design comps
  4. Front End Development
  5. Back End Development
  6. Hook it all up
  7. Test/QA
  8. Launch

(image from balsamiq)

A Few Problems:

  • Design & Development team disconnect
  • Can take longer - FE team might not be able to even start before design comps are done
  • Many traditional designers don't know code - could be making something very hard/impossible to build
  • Mobile First, then Desktop is a good first step, but still poses problems because you can't make "flexible" designs

😬

How we used to do it:

  1. Business requirements
  2. Wireframes
  3. Full design comps
  4. Front End Development
  5. Back End Development
  6. Hook it all up
  7. Test/QA
  8. Launch

How we do it now:

  1. Business requirements
  2. (Live)? Wireframes
  3. Live Style Guide (HTML/SASS/JSX) with Components (Start Testing)
  4. Hook up components to API/Backend (Finish Testing)
  5. Launch

Style Guides

🎨

Why We Like Them:

One-Stop Reference for:

  • Brand standards
  • Typography
  • Colors
  • Various Basic Component Styles

Why We Like Them:

One-Stop Reference for:

  • Brand standards
  • Typography
  • Colors
  • Various Basic Component Styles

Why our clients like them:

"Live" Style Guides

  • Get started in the browser right away
  • Designers should at least know enough code to start styling type, buttons, etc... Sketch has code export!
  • Live previews on all devices - less surprises
  • Front End Developers are on board right away, Design decisions can be documented via version control

Documentation

(Everything has an API)

📑

Who's done Front End Docs?

(Raise your hands)

🙋

Why do Front End Docs?

  • One place to reference what parts of an application may look like
  • Easier to show options or explain how your project's code works
  • Backend developers can stay consistent
  • Test functionality of application pieces in different browsers/devices

Good Front End Documentation Examples:

What should go into Front End Docs?

  • Style Guide items are a good place to start (first page)
  • Show all possible button combinations
  • Offer copy/paste starting code for application pieces - "hey, this is how to get a modal to work"
  • How to get the project up and running locally
  • Methodologies for writing your SASS/CSS, JS, and other things
  • COMPONENTS...

Components

What is a component?

a part or element of a larger whole, especially a part of a machine or vehicle

Why use components?

  • Keep things DRY (don't repeat yourself)
  • Easy to divide up labor/work for teams
  • Easy to re-arrange and put together new views
  • Possible to share/publish/open source/reuse
  • Changes everything!

"So what does this look like?"

(Live Demo)

Thanks!

Any Questions?

Building Component-Based Style Guides & Documentation

By Julien Melissas

Building Component-Based Style Guides & Documentation

  • 3,749