Generate Styleguides for Every Project – Marc Friederich – Awesome Generated web living styleguides

View Github Repository Open presentation in a new window

antistatique

See all presentation from antistatique

Generate Styleguides for Every Project – Marc Friederich – Awesome Generated web living styleguides

1 0

slides-styleguide-by-default

A presentation about styleguide driven development

On Github antistatique / slides-styleguide-by-default

Generate Styleguides for Every Project

Welcome to my presentation about having a generated styleguide as a living documentation for every project. Today - Understand what is a web styleguide - Why using a styleguide make things easy - And how easy it should be to setup a new project ("$yo styleguide")

Marc Friederich

Software designer & co-founder of ...

github.com/zufrieden

@zufrieden

My name is Marc. I'm so positive that my twitter handle is Zufrieden. I'm a so-called software designer, meaning the UX guy who code and design working with HTML since 15 years (I'm getting old). I'm also co-founder of ...

swiss web agency

Digital first / User needs / Problem solving / Handcrafted quality / Ping pong

github.com/antistatique

@antistatique

Antistatique. A web agency of about 10 people. Enjoying building digital strategy, web solutions focused on user needs.
Who is using HTML for his presentation ? Great ! So if you publish it on github, you'll be featured on slidedeck.io. One of our product at Antistatique.
And Devicelab where I hope you'll come one day to test your applications, web products and newsletters (You'll find more devicelab address on opendevicelab.com). But we are not here to talk about me.

Awesome Generated web living styleguides

By default

We're here to talk about Styleguides, neat, automated, digital, live. And why it should be the default. Let's start with "styleguide definition" ... But first. Raise your hand who already use webstyleguide ? generated ?

Web styleguides definition

Web site style guides cover a publication's visual and technical aspects, along with text. Many style guides are revised periodically to accommodate changes in conventions and usage.

Wikipedia A styleguide is a tool to set standards in how the brand identity is communicated. Important in this definition is "visual and technical" and "revised periodically"
This exemple from US boy scout showing how to use their logo. What are the colours
You may be familiar with those binders This exemple from the New York transit authority 1970. How you should use the different element
A web styleguide (as digital enter the game) it's interactive. For instance this is the the lonelyplanet online styleguide
They provide ready to use components like you could find with bootstrap, foundation, pears etc .. And now that we have the same understanding of web styleguides let's look at what problem are we solving ...

Do we need a styleguide for every project?

Do we really need a styleguide for every project ...

Let's go back 3 years ago ...

I'd like to share my own experience and how we came from nothing to styleguide by default
Those 2 guys are the designers, and those 3 there are coding CSS/HTML. We were a team working together on the same code.
Those guys are serious ! They are smiling Then we won this big client, a real estate company! They have a website with a search engine, some landing pages and other websites dedicated to estate properties.
They want the same design on all their websites, intranet and digital. So we start by using the same CSS accross all websites 
ul.nav-main .nav-sub .nav-sub-top, ul.nav-language .nav-sub .nav-sub-top {}
When we needed a new component to implement, we were writing new lines, to be sure not to breack anything 9000 lines of CSS, with no documentation, used accross 10 websites. Main website with other landing page ... using the same CSS Collaboration with in-house developers, the need for a documentation (which stay up to date). - we needed to do something
  • Duplicated code
  • Dead code
  • Communication problem
  • Hard to test
CSS copy past Not used code (plugin) Between designers and developpers TESTing browser, RWD

But How!?

I was looking for a solution ... Lost, alone ... seeking north
In Helsinki, finland for the webshaped frontend conference, I saw this guy : Kyle ! He is working at Github. He was talking about how cool it is to have a documentation. He caught my interest Let's see how it works 
/*
# Text components
## Titles
````

My title number 1

```` */ h1{ color: #262626; font-weight: 700; } You have your documentation with the code (like javadoc) You create a structure with Markdown syntax (like github) This exemple : a title H1.
The generated documentation from the code shows titles etc ...
  • Think before you code
  • Communication designers/developers
  • Envolve with your project
  • Testing platform
  • A better web!
full of benefits. Document before you code, help you go modular Styleguide first it's a perfect tool to communicate earlyer in the frontend coding process with the designer A styleguide that envolve with your product Testing responsive, accessibility, multiple browser
We tried some tool available (styledocco, KSS, KaleyStyleguide) and finally we built our own tool called : YSS
2 year later ... We used our tool for every project we had and start talking about it ....

Hired to produce a web styleguide

For Switzerland public administration

We only had to create the styleguide
We had to produce a styleguide for all the administration websites. Meaning a large scale project with many actors
We choose Hologram because more contributed than our YSS, still on markdown, same documentation syntax, themable.
Now that you saw how useful it is to have a styleguide by default, let's see how easy it is to setup

Styleguide by default

Use a generated living styleguide for your next project!

Make it default, make it easy!

Generate a styleguide from a generator

We use bootstrap as a base for every project, from a small website to a complexe application. It's a good base to start with. Tested in every browser, works well with a ccessibility. Don't reinvent the wheel ;-)
We need also Bower to manage dependencies like bootstrap. It allow us to update the project with ease
Hologram as I showed you earlier. Generate the webstyleguide from the code
We created Holostrap, simply a bootstrap documentation adapted to Hologram. So right out of the box, you have all bootstrap components documented in your styleguide
Then we created Cortana, a nice hologram theme with search capabilities
And finally Gulp to manage task such as generate CSS from SASS, minimify css, launch hologram, deploy
And because it will takes 2 hours to setup all those tools, We created a Yeoman recipe. 
$ yo styleguide
Easy as .... this
Yeoman asks you the name of the project and voilà ... 
.
├── README.md
├── assets
├── bower.json
├── gulpfile.js
├── hologram_config.yml
├── node_modules
├── package.json
└── robots.txt
Here is the structure when Yeoman finished is first setup 
assets
├── README.md
├── doc_assets
│   ├── _footer.html
│   └── _header.html
├── fonts
├── js
│   └── FEC14.js
└── sass
├── FEC14-mixins.scss
├── FEC14-variables.scss
├── FEC14.scss
├── bootstrap-variables.scss
├── bootstrap.scss
├── components
├── javascript
└── layout
Taking a closer look to the assets directory, you see where you will start to work, changing bootstrap variable and start implementing/documenting your first modular components

hologram_config.yml 

source: ./assets

destination: ./styleguide

documentation_assets: ./bower_components/Cortana

dependencies:
- ./build

css_include:
- 'css/FEC14.css'

index: README
Hologram configuation says. Look at assets folder, generate the styleguide in styleguide folder using Cortana theme 
$ gulp serve
See it in action, we're changing primary color from blue to green

Workflow

Yeoman scaffolding Dependencies managment with npm and Bower Running tasks with Gulp serve with BrowserSync Modular styles inside the styleguide 4 again and again...

To conclude

What I would like you to remember from this talk is ...
Start with a styleguide Communicate more often Develop future proof Think modular first Contribute! It's open source!

Give it a try

Thank you

Questions?

Find this presentation on slidedeck.io/antistatique or antistatique.github.io/slides-styleguide-by-default

Sources