Style Guides: Where designers and engineers meet (shorter version)

(This is a shorter version of this talk: https://speakerdeck.com/foliosus/style-guides-where-designers-and-engineers-meet)

All too often the designers and engineers on a team are seen as being at odds with each other. It turns out that there's a huge area of overlap, where we all want the same things. The designer wants the button to move down 2 pixels, so it lines up to the baseline correctly. The engineer doesn't want to have to worry about the baseline, and doesn't want to write extra code to make that one button line up. We can all agree on the rules. We can have it all!

Putting a style guide front and center in your workflow can make these problems go away, while simplifying the eventual redesign that you'll have to do. A good style guide isn't a PDF that tells you if you should use the Oxford comma or not. (You should, by the way.) It is a visual pattern library, a design inventory, and an engineering guide all in one. It's built in your app, using the same widgets that you use to build the app, in the same way. It's a living, breathing example of how an engineer builds the designs, and makes all of the system-wide rules clear.

Designers can use the style guide as a visual pattern library. They can look at all of the pieces together, and decide that one widget needs some work. They can look at the changes they're advocating for in a particular widget to see how it fits with the rest of the site.

Engineers can use the style guide as a how-to guide for the implementation of complex patterns. The code will reveal the implementation details, making them easy to reproduce. The shape of the code that powers the UI is made visible, letting you know when refactoring or other maintenance is necessary.

Both sides can look at the style guide and understand the system that they are responsible for.

This talk looks at how you can build a functional, beautiful style guide that will help you solve many of the long-term site management problems we all have. It requires a certain approach to building your front-end that's based on small repeatable units, strong semantics, and something like OOCSS. You will walk away with a concrete understanding of how the style guide looks and behaves in code, along with the semantic and technical underpinnings necessary to make it a feasible goal.

Transcript

1. STYLE GUIDES Where designers and engineers meet Brent Miller, @foliosus
 Lead engineer at New Relic
2. @foliosus http://bit.ly/living-style-guides-short ENGINEER http://flic.kr/p/8kQoCU
3. @foliosus http://bit.ly/living-style-guides-short DESIGNER http://flic.kr/p/86pfMN
4. ENGINEER https://flic.kr/p/bRHngB
5. DESIGNER https://flic.kr/p/7Ac6Y9
6. @foliosus http://bit.ly/living-style-guides-short WRONG
7. BOTH https://flic.kr/p/5mBkp6
8. @foliosus http://bit.ly/living-style-guides-short WHERE ARE YOU? Designer Engineer me, now me, 2 years ago
9. @foliosus http://bit.ly/living-style-guides-short ROAD MAP It’s all about rules Typography Living style guides The inevitable redesign
10. @foliosus http://bit.ly/living-style-guides-short ROAD MAP It’s all about rules Typography Living style guides The inevitable redesign
11. It’s all about the rules
12. @foliosus http://bit.ly/living-style-guides-short EVERYBODY LIKES RULES
13. @foliosus http://bit.ly/living-style-guides-short http://shahirzag.com Bad leading Terrible
 kerning Spacing
 issues
14. @foliosus http://bit.ly/living-style-guides-short How to
 piss off
 your
 designer
 friends
 and give
 them a
 migraine.
15. www.arngren.net
16. @foliosus http://bit.ly/living-style-guides-short DESIGNERS CREATE SYSTEMS THAT GOVERN EXPERIENCE proposition
17. @foliosus http://bit.ly/living-style-guides-short ENGINEERS CREATE SYSTEMS THAT GOVERN FUNCTION proposition
18. @foliosus http://bit.ly/living-style-guides-short
19. @foliosus http://bit.ly/living-style-guides-short ROAD MAP It’s all about rules Typography Living style guides The inevitable redesign
20. Typography
21. @foliosus http://bit.ly/living-style-guides-short IT’S ALL ABOUT THE RULES
26. @foliosus http://bit.ly/living-style-guides-short @include establish-baseline;! ! body {! color: $body_text_color;! @include default_font_family;! }! ! p, ul, ol, blockquote, pre, td, th, label, dt, dd {! @include set-font-size(0);! @include margin-trailer(1);! }!
27. @foliosus http://bit.ly/living-style-guides-short @include establish-baseline;! ! body {! color: $body_text_color;! @include default_font_family;! }! ! p, ul, ol, blockquote, pre, td, th, label, dt, dd {! @include set-font-size(0);! @include margin-trailer(1);! }!
28. @foliosus http://bit.ly/living-style-guides-short @include establish-baseline;! ! body {! color: $body_text_color;! @include default_font_family;! }! ! p, ul, ol, blockquote, pre, td, th, label, dt, dd {! @include set-font-size(0);! @include margin-trailer(1);! }!
29. @foliosus http://bit.ly/living-style-guides-short @include establish-baseline;! ! body {! color: $body_text_color;! @include default_font_family;! }! ! p, ul, ol, blockquote, pre, td, th, label, dt, dd {! @include set-font-size(0);! @include margin-trailer(1);! }!
30. @foliosus http://bit.ly/living-style-guides-short // Use the modular scale to get bigger/smaller fonts than
 // the default. The $adjustment parameter is 0 for the
 // default font size, or between -2 and +4 for 2 sizes
 // smaller to 4 sizes bigger than the default." @mixin set_font_size($adjustment: 0) {! $new_size: modular_scale_size($adjustment);! $new_line_count: modular_scale_lines($adjustment);! @include adjust-font-size-to($new_size, $new_line_count);! }!
31. @foliosus http://bit.ly/living-style-guides-short // Get the font-size for the number of steps
 // above/below body text. Our modular scale" // uses a ratio of 1.3 between levels" @function modular_scale_size($adjustment: 0) {! @if $adjustment == -2 {! @return 11px;! } @else if $adjustment == -1 {! @return 12px;! } @else if $adjustment == 0 {! @return $base-font-size;! } @else if $adjustment == 1 {! @return 18px;! …! } @else if $adjustment == 5 {! @return 43px;! }! }!
32. @foliosus http://bit.ly/living-style-guides-short // Use the modular scale to get bigger/smaller fonts than
 // the default. The $adjustment parameter is 0 for the
 // default font size, or between -2 and +4 for 2 sizes
 // smaller to 4 sizes bigger than the default." @mixin set_font_size($adjustment: 0) {! $new_size: modular_scale_size($adjustment);! $new_line_count: modular_scale_lines($adjustment);! @include adjust-font-size-to($new_size, $new_line_count);! }!
33. @foliosus http://bit.ly/living-style-guides-short YOU HAVE NO CHOICES!
 
 YOU ALWAYS GET IT RIGHT.
34. @foliosus http://bit.ly/living-style-guides-short WINNING!
35. @foliosus http://bit.ly/living-style-guides-short class CssModularScaleTest < ActiveSupport::TestCase! files = […] // Load the files you care about, rejecting directories! ! # All font-size declarations in our CSS must use the modular scale,
 # defined at the top of _typography.scss. This test asserts that all! # of our CSS uses the modular scale.! files.each do |filename|! context "#{filename}" do! should 'only use the modular scale for declaring font sizes' do! regexp = /.*?font-size:\s*(.*?);/i! open(filename) do |f|! # Look for statements like these:! # font-size: 12px! # font-size: 3%! matches = f.grep(regexp)! passing = true! matches.each do |match|! next unless passing! match =~ regexp # Get the capture parameter, $1! passing = false unless $1.in?(['100%', 'inherit'])! end! unless passing! flunk "Must use set-font-size(x) instead of font-size: x.” +! ! ! ! ! “font-size: 100% and font-size: inherited are allowed.”! end! end! end! end!
36. @foliosus http://bit.ly/living-style-guides-short class CssModularScaleTest < ActiveSupport::TestCase! files = […] // Load the files you care about, rejecting directories! ! # All font-size declarations in our CSS must use the modular scale,
 # defined at the top of _typography.scss. This test asserts that all! # of our CSS uses the modular scale.! files.each do |filename|! context "#{filename}" do! should 'only use the modular scale for declaring font sizes' do! regexp = /.*?font-size:\s*(.*?);/i! open(filename) do |f|! # Look for statements like these:! # font-size: 12px! # font-size: 3%! matches = f.grep(regexp)! passing = true! matches.each do |match|! next unless passing! match =~ regexp # Get the capture parameter, $1! passing = false unless $1.in?(['100%', 'inherit'])! end! unless passing! flunk "Must use set-font-size(x) instead of font-size: x.” +! ! ! ! ! “font-size: 100% and font-size: inherited are allowed.”! end! end! end! end!
37. @foliosus http://bit.ly/living-style-guides-short class CssModularScaleTest < ActiveSupport::TestCase! files = […] // Load the files you care about, rejecting directories! ! # All font-size declarations in our CSS must use the modular scale,
 # defined at the top of _typography.scss. This test asserts that all! # of our CSS uses the modular scale.! files.each do |filename|! context "#{filename}" do! should 'only use the modular scale for declaring font sizes' do! regexp = /.*?font-size:\s*(.*?);/i! open(filename) do |f|! # Look for statements like these:! # font-size: 12px! # font-size: 3%! matches = f.grep(regexp)! passing = true! matches.each do |match|! next unless passing! match =~ regexp # Get the capture parameter, $1! passing = false unless $1.in?(['100%', 'inherit'])! end! unless passing! flunk "Must use set-font-size(x) instead of font-size: x.” +! ! ! ! ! “font-size: 100% and font-size: inherited are allowed.”! end! end! end! end!
38. @foliosus http://bit.ly/living-style-guides-short class CssModularScaleTest < ActiveSupport::TestCase! files = […] // Load the files you care about, rejecting directories! ! # All font-size declarations in our CSS must use the modular scale,
 # defined at the top of _typography.scss. This test asserts that all! # of our CSS uses the modular scale.! files.each do |filename|! context "#{filename}" do! should 'only use the modular scale for declaring font sizes' do! regexp = /.*?font-size:\s*(.*?);/i! open(filename) do |f|! # Look for statements like these:! # font-size: 12px! # font-size: 3%! matches = f.grep(regexp)! passing = true! matches.each do |match|! next unless passing! match =~ regexp # Get the capture parameter, $1! passing = false unless $1.in?(['100%', 'inherit'])! end! unless passing! flunk "Must use set-font-size(x) instead of font-size: x.” +! ! ! ! ! “font-size: 100% and font-size: inherited are allowed.”! end! end! end! end!
39. @foliosus http://bit.ly/living-style-guides-short /.*?font-size:\s*(.*?);/i capture the value
 of the font-size
40. @foliosus http://bit.ly/living-style-guides-short class CssModularScaleTest < ActiveSupport::TestCase! files = […] // Load the files you care about, rejecting directories! ! # All font-size declarations in our CSS must use the modular scale,
 # defined at the top of _typography.scss. This test asserts that all! # of our CSS uses the modular scale.! files.each do |filename|! context "#{filename}" do! should 'only use the modular scale for declaring font sizes' do! regexp = /.*?font-size:\s*(.*?);/i! open(filename) do |f|! # Look for statements like these:! # font-size: 12px! # font-size: 3%! matches = f.grep(regexp)! passing = true! matches.each do |match|! next unless passing! match =~ regexp # Get the capture parameter, $1! passing = false unless $1.in?(['100%', 'inherit'])! end! unless passing! flunk "Must use set-font-size(x) instead of font-size: x.” +! ! ! ! ! “font-size: 100% and font-size: inherited are allowed.”! end! end! end! end!
41. @foliosus http://bit.ly/living-style-guides-short class CssModularScaleTest < ActiveSupport::TestCase! files = […] // Load the files you care about, rejecting directories! ! # All font-size declarations in our CSS must use the modular scale,
 # defined at the top of _typography.scss. This test asserts that all! # of our CSS uses the modular scale.! files.each do |filename|! context "#{filename}" do! should 'only use the modular scale for declaring font sizes' do! regexp = /.*?font-size:\s*(.*?);/i! open(filename) do |f|! # Look for statements like these:! # font-size: 12px! # font-size: 3%! matches = f.grep(regexp)! passing = true! matches.each do |match|! next unless passing! match =~ regexp # Get the capture parameter, $1! passing = false unless $1.in?(['100%', 'inherit'])! end! unless passing! flunk "Must use set-font-size(x) instead of font-size: x.” +! ! ! ! ! “font-size: 100% and font-size: inherited are allowed.”! end! end! end! end!
42. @foliosus http://bit.ly/living-style-guides-short class CssModularScaleTest < ActiveSupport::TestCase! files = […] // Load the files you care about, rejecting directories! ! # All font-size declarations in our CSS must use the modular scale,
 # defined at the top of _typography.scss. This test asserts that all! # of our CSS uses the modular scale.! files.each do |filename|! context "#{filename}" do! should 'only use the modular scale for declaring font sizes' do! regexp = /.*?font-size:\s*(.*?);/i! open(filename) do |f|! # Look for statements like these:! # font-size: 12px! # font-size: 3%! matches = f.grep(regexp)! passing = true! matches.each do |match|! next unless passing! match =~ regexp # Get the capture parameter, $1! passing = false unless $1.in?(['100%', 'inherit'])! end! unless passing! flunk "Must use set-font-size(x) instead of font-size: x.” +! ! ! ! ! “font-size: 100% and font-size: inherited are allowed.”! end! end! end! end!
43. @foliosus http://bit.ly/living-style-guides-short class CssModularScaleTest < ActiveSupport::TestCase! files = […] // Load the files you care about, rejecting directories! ! # All font-size declarations in our CSS must use the modular scale,
 # defined at the top of _typography.scss. This test asserts that all! # of our CSS uses the modular scale.! files.each do |filename|! context "#{filename}" do! should 'only use the modular scale for declaring font sizes' do! regexp = /.*?font-size:\s*(.*?);/i! open(filename) do |f|! # Look for statements like these:! # font-size: 12px! # font-size: 3%! matches = f.grep(regexp)! passing = true! matches.each do |match|! next unless passing! match =~ regexp # Get the capture parameter, $1! passing = false unless $1.in?(['100%', 'inherit'])! end! unless passing! flunk "Must use set-font-size(x) instead of font-size: x.” +! ! ! ! ! “font-size: 100% and font-size: inherited are allowed.”! end! end! end! end!
44. @foliosus http://bit.ly/living-style-guides-short class CssModularScaleTest < ActiveSupport::TestCase! files = […] // Load the files you care about, rejecting directories! ! # All font-size declarations in our CSS must use the modular scale,
 # defined at the top of _typography.scss. This test asserts that all! # of our CSS uses the modular scale.! files.each do |filename|! context "#{filename}" do! should 'only use the modular scale for declaring font sizes' do! regexp = /.*?font-size:\s*(.*?);/i! open(filename) do |f|! # Look for statements like these:! # font-size: 12px! # font-size: 3%! matches = f.grep(regexp)! passing = true! matches.each do |match|! next unless passing! match =~ regexp # Get the capture parameter, $1! passing = false unless $1.in?(['100%', 'inherit'])! end! unless passing! flunk "Must use set-font-size(x) instead of font-size: x.” +! ! ! ! ! “font-size: 100% and font-size: inherited are allowed.”! end! end! end! end!
45. @foliosus http://bit.ly/living-style-guides-short #WINNING
46. @foliosus http://bit.ly/living-style-guides-short YOU HAVE NO CHOICES!
 
 YOU ALWAYS GET IT RIGHT.
47. @foliosus http://bit.ly/living-style-guides-short ROAD MAP It’s all about rules Typography Living style guides The inevitable redesign
48. https://flic.kr/p/aRefmB Living Style
 Guides ݪ॓
49. @foliosus http://bit.ly/living-style-guides-short WHAT IS A
 LIVING
 STYLE
 GUIDE?
50. https://flic.kr/p/bR2ZmM #fail
51. @foliosus http://bit.ly/living-style-guides-short ON THE INTARWEBZ, WE MOVE TOO FAST FOR BOOKS
 WE NEED CODE
52. @foliosus http://bit.ly/living-style-guides-short WE NEED CODE TO SHOW US THE CODE AND THE INTERFACE
53. Navigation Example Name Code Example
 code
54. It’s alive!!! https://flic.kr/p/mukwAt
55. @foliosus http://bit.ly/living-style-guides-short WHY?
56. @foliosus http://bit.ly/living-style-guides-short IT’S IN THE CODE!
57. @foliosus http://bit.ly/living-style-guides-short A living style guide is a part of your UI, and uses the code that generates the UI YO DAWG!
58. @foliosus http://bit.ly/living-style-guides-short %h3 Success/info flash message! .description A positive, or equivocal
 message for the user. Can be given a! hide button! %code! :plain! = ui_flash_message 'Message contents’,! ! ! ! ! ! type: :success, ! actions: link_to('Hide', '#')! .example! = ui_flash_message ‘Message contents’,! ! ! ! ! type: :success,! actions: link_to('Hide', '#')!
59. @foliosus http://bit.ly/living-style-guides-short %h3 Success/info flash message! .description A positive, or equivocal
 message for the user. Can be given a! hide button! %code! :plain! = ui_flash_message 'Message contents’,! ! ! ! ! ! type: :success, ! actions: link_to('Hide', '#')! .example! = ui_flash_message ‘Message contents’,! ! ! ! ! type: :success,! actions: link_to('Hide', '#')!
60. @foliosus http://bit.ly/living-style-guides-short %h3 Success/info flash message! .description A positive, or equivocal
 message for the user. Can be given a! hide button! %code! :plain! = ui_flash_message 'Message contents’,! ! ! ! ! ! type: :success, ! actions: link_to('Hide', '#')! .example! = ui_flash_message ‘Message contents’,! ! ! ! ! type: :success,! actions: link_to('Hide', '#')!
61. @foliosus http://bit.ly/living-style-guides-short %h3 Success/info flash message! .description A positive, or equivocal
 message for the user. Can be given a! hide button! %code! :plain! = ui_flash_message 'Message contents’,! ! ! ! ! ! type: :success, ! actions: link_to('Hide', '#')! .example! = ui_flash_message ‘Message contents’,! ! ! ! ! type: :success,! actions: link_to('Hide', '#')!
62. @foliosus http://bit.ly/living-style-guides-short %h3 Success/info flash message! .description A positive, or equivocal
 message for the user. Can be given a! hide button! %code! :plain! = ui_flash_message 'Message contents’,! ! ! ! ! ! type: :success, ! actions: link_to('Hide', '#')! .example! = ui_flash_message ‘Message contents’,! ! ! ! ! type: :success,! actions: link_to('Hide', '#')!
63. @foliosus http://bit.ly/living-style-guides-short %h3 Success/info flash message! .description A positive, or equivocal
 message for the user. Can be given a! hide button! %code! :plain! = ui_flash_message 'Message contents’,! ! ! ! ! ! type: :success, ! actions: link_to('Hide', '#')! .example! = ui_flash_message ‘Message contents’,! ! ! ! ! type: :success,! actions: link_to('Hide', '#')!
64. @foliosus http://bit.ly/living-style-guides-short THE WIDGET ‣ Code abstraction ‣ Semantic naming ‣ Generates (complex) HTML markup ‣ Appears in multiple places ‣ Coupled to CSS for presentation and JS for behavior
65. @foliosus http://bit.ly/living-style-guides-short LIVING STYLE GUIDE MVP 1.Name 2.Description 3.Example 4.Code
66. SEMANTICS MATTER
67. #fail
68. @foliosus http://bit.ly/living-style-guides-short SEMANTICS ARE A CONTRACT
69. @foliosus http://bit.ly/living-style-guides-short AS THE SITE GETS WORKED ON, PRESENTATION AND BEHAVIOR CHANGE ! SEMANTICS DON’T
70. @foliosus http://bit.ly/living-style-guides-short Semantics are a contract between all consumers of the site
71. @foliosus http://bit.ly/living-style-guides-short ‣ Engineers ‣ Designers ‣ QA ‣ Support ‣ Customers
72. @foliosus http://bit.ly/living-style-guides-short YOU TAKE CARE OF MY CONTENT, AND I’LL TAKE CARE OF YOURS The Contract
73. @foliosus http://bit.ly/living-style-guides-short WHAT IS A
 LIVING
 STYLE
 GUIDE? take 2!
74. @foliosus http://bit.ly/living-style-guides-short ‣ A design inventory ‣ A visual pattern library (can coach users!) ‣ Code to simplify UI generation ‣ A shortcut to faster development ‣ Iterative design improvements ‣ Contract for shared maintenance
75. bit.ly/devsignercon_semantics_1 category
 drilldown
 list
76. bit.ly/devsignercon_semantics_2 search
 result
77. @foliosus http://bit.ly/living-style-guides-short THE WIDGET ‣ Code abstraction ‣ Semantic naming ‣ Generates (complex) HTML markup ‣ Appears in multiple places ‣ Coupled to CSS for presentation and JS for behavior http://bit.ly/devsignercon_semantics_1
78. @foliosus http://bit.ly/living-style-guides-short ROAD MAP It’s all about rules Typography Living style guides The inevitable redesign
79. THE REDESIGN
 IS INEVITABLE https://flic.kr/p/dY8PZF
80. @foliosus http://bit.ly/living-style-guides-short NOBODY WANTS PLANNED OBSOLESCENCE
81. @foliosus http://bit.ly/living-style-guides-short OUR RECORD:
 1 PERSON, 10 DAYS* *your mileage may vary
82. THANK YOU! @foliosus https://flic.kr/p/bhyT8B bit.ly/devsignercon-style-guides