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:
- Business requirements
- Wireframes
- Full design comps
- Front End Development
- Back End Development
- Hook it all up
- Test/QA
- 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:
- Business requirements
- Wireframes
- Full design comps
- Front End Development
- Back End Development
- Hook it all up
- Test/QA
- Launch
How we do it now:
- Business requirements
- (Live)? Wireframes
- Live Style Guide (HTML/SASS/JSX) with Components (Start Testing)
- Hook up components to API/Backend (Finish Testing)
- 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!