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.

The talk was originally delivered at DevsignerCon, on May 24, 2014: http://devsignercon.com/devsigner-2014/session/style-guides-where-designers-and-engineers-meet

Transcript

1. STYLE GUIDES Where designers and engineers meet Brent Miller, @foliosus
 Lead engineer at New Relic
2. @foliosus http://bit.ly/devsignercon-style-guides ENGINEER http://flic.kr/p/8kQoCU
3. @foliosus http://bit.ly/devsignercon-style-guides 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/devsignercon-style-guides WRONG
7. BOTH https://flic.kr/p/5mBkp6
8. @foliosus http://bit.ly/devsignercon-style-guides WHERE ARE YOU? Designer Engineer me me, 2 years ago
9. @foliosus http://bit.ly/devsignercon-style-guides ROAD MAP It’s all about rules Typography Living style guides The inevitable redesign
10. @foliosus http://bit.ly/devsignercon-style-guides 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/devsignercon-style-guides EVERYBODY LIKES RULES
13. @foliosus http://bit.ly/devsignercon-style-guides http://shahirzag.com Bad leading Terrible
 kerning Spacing
 issues
14. @foliosus http://bit.ly/devsignercon-style-guides How to
 piss off
 your
 designer
 friends
 and give
 them a
 migraine.
15. www.arngren.net
16. @foliosus http://bit.ly/devsignercon-style-guides DESIGNERS CREATE SYSTEMS THAT GOVERN EXPERIENCE proposition
17. @foliosus http://bit.ly/devsignercon-style-guides LOGOS
18. @foliosus http://bit.ly/devsignercon-style-guides TYPE
19. @foliosus http://bit.ly/devsignercon-style-guides GRIDS
20. @foliosus http://bit.ly/devsignercon-style-guides INTERACTIONS
21. @foliosus http://bit.ly/devsignercon-style-guides LAYOUTS
22. @foliosus http://bit.ly/devsignercon-style-guides A DESIGN SYSTEM:
 SMALL, REPEATED ELEMENTS THAT COMPOSE NICELY deliverable
23. @foliosus http://bit.ly/devsignercon-style-guides ENGINEERS CREATE SYSTEMS THAT GOVERN FUNCTION proposition
24. @foliosus http://bit.ly/devsignercon-style-guides SINGLE RESPONSIBILITY http://bit.ly/S7HKVG
25. @foliosus http://bit.ly/devsignercon-style-guides STAY DRY https://flic.kr/p/bF69Tp
26. @foliosus http://bit.ly/devsignercon-style-guides COMPOSITION OVER INHERITANCE https://flic.kr/p/ejk6pe
27. @foliosus http://bit.ly/devsignercon-style-guides KEEP IT SIMPLE, STUPID (KISS) https://flic.kr/p/6Ffq2Q
28. @foliosus http://bit.ly/devsignercon-style-guides AN OOP SYSTEM:
 SMALL, REPEATABLE OBJECTS THAT
 INTERACT NICELY deliverable
29. JACKPOT https://flic.kr/p/dthsx
30. @foliosus http://bit.ly/devsignercon-style-guides Designers create systems that govern experience Engineers create systems that govern function our earlier propositions
31. @foliosus http://bit.ly/devsignercon-style-guides A design system:
 small, repeated elements that compose nicely An OOP system:
 small, repeatable objects that interact nicely our earlier deliverables
32. @foliosus http://bit.ly/devsignercon-style-guides ROAD MAP It’s all about rules Typography Living style guides The inevitable redesign
33. Typography
34. @foliosus http://bit.ly/devsignercon-style-guides IT’S ALL ABOUT THE RULES
39. @foliosus http://bit.ly/devsignercon-style-guides @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);! }!
40. @foliosus http://bit.ly/devsignercon-style-guides @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);! }!
41. @foliosus http://bit.ly/devsignercon-style-guides @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);! }!
42. @foliosus http://bit.ly/devsignercon-style-guides @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);! }!
43. @foliosus http://bit.ly/devsignercon-style-guides // 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);! }!
44. @foliosus http://bit.ly/devsignercon-style-guides // 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;! }! }!
45. @foliosus http://bit.ly/devsignercon-style-guides // 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);! }!
46. @foliosus http://bit.ly/devsignercon-style-guides YOU HAVE NO CHOICES!
 
 YOU ALWAYS GET IT RIGHT.
47. @foliosus http://bit.ly/devsignercon-style-guides WINNING!
48. @foliosus http://bit.ly/devsignercon-style-guides 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!
49. @foliosus http://bit.ly/devsignercon-style-guides 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!
50. @foliosus http://bit.ly/devsignercon-style-guides 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!
51. @foliosus http://bit.ly/devsignercon-style-guides 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!
52. @foliosus http://bit.ly/devsignercon-style-guides /.*?font-size:\s*(.*?);/i capture the value
 of the font-size
53. @foliosus http://bit.ly/devsignercon-style-guides 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!
54. @foliosus http://bit.ly/devsignercon-style-guides 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!
55. @foliosus http://bit.ly/devsignercon-style-guides 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!
56. @foliosus http://bit.ly/devsignercon-style-guides 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!
57. @foliosus http://bit.ly/devsignercon-style-guides 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!
58. @foliosus http://bit.ly/devsignercon-style-guides #WINNING
59. @foliosus http://bit.ly/devsignercon-style-guides YOU HAVE NO CHOICES!
 
 YOU ALWAYS GET IT RIGHT.
60. @foliosus http://bit.ly/devsignercon-style-guides ROAD MAP It’s all about rules Typography Living style guides The inevitable redesign
61. https://flic.kr/p/aRefmB Living Style
 Guides ݪ॓
62. @foliosus http://bit.ly/devsignercon-style-guides WHAT IS A
 LIVING
 STYLE
 GUIDE?
63. https://flic.kr/p/bR2ZmM #fail
64. @foliosus http://bit.ly/devsignercon-style-guides ON THE INTARWEBZ, WE MOVE TOO FAST FOR BOOKS
 WE NEED CODE
65. @foliosus http://bit.ly/devsignercon-style-guides WE NEED CODE TO SHOW US THE CODE AND THE INTERFACE
66. Navigation Example Name Code Example
 code
67. It’s alive!!! https://flic.kr/p/mukwAt
68. @foliosus http://bit.ly/devsignercon-style-guides WHY?
69. @foliosus http://bit.ly/devsignercon-style-guides IT’S IN THE CODE!
70. @foliosus http://bit.ly/devsignercon-style-guides A living style guide is a part of your UI, and uses the code that generates the UI YO DAWG!
71. @foliosus http://bit.ly/devsignercon-style-guides %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', '#')!
72. @foliosus http://bit.ly/devsignercon-style-guides %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', '#')!
73. @foliosus http://bit.ly/devsignercon-style-guides %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', '#')!
74. @foliosus http://bit.ly/devsignercon-style-guides %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', '#')!
75. @foliosus http://bit.ly/devsignercon-style-guides %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', '#')!
76. @foliosus http://bit.ly/devsignercon-style-guides %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', '#')!
77. @foliosus http://bit.ly/devsignercon-style-guides THE WIDGET ‣ Code abstraction ‣ Semantic naming ‣ Generates (complex) HTML markup ‣ Appears in multiple places ‣ Coupled to CSS for presentation and JS for behavior
78. @foliosus http://bit.ly/devsignercon-style-guides LIVING STYLE GUIDE MVP 1.Name 2.Description 3.Example 4.Code
79. SEMANTICS MATTER
80. #fail
81. @foliosus http://bit.ly/devsignercon-style-guides SEMANTICS ARE A CONTRACT
82. @foliosus http://bit.ly/devsignercon-style-guides AS THE SITE GETS WORKED ON, PRESENTATION AND BEHAVIOR CHANGE ! SEMANTICS DON’T
83. @foliosus http://bit.ly/devsignercon-style-guides Semantics are a contract between all consumers of the site
84. @foliosus http://bit.ly/devsignercon-style-guides ‣ Engineers ‣ Designers ‣ QA ‣ Support ‣ Customers
85. @foliosus http://bit.ly/devsignercon-style-guides YOU TAKE CARE OF MY CONTENT, AND I’LL TAKE CARE OF YOURS The Contract
86. @foliosus http://bit.ly/devsignercon-style-guides WHAT IS A
 LIVING
 STYLE
 GUIDE? take 2!
87. @foliosus http://bit.ly/devsignercon-style-guides ‣ 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
88. @foliosus http://bit.ly/devsignercon-style-guides ACTIVITY TIME! ! LET’S FIGURE OUT
 SOME SEMANTICS
89. bit.ly/devsignercon_semantics_1 category
 drilldown
 list
90. bit.ly/devsignercon_semantics_2 search
 result
91. @foliosus http://bit.ly/devsignercon-style-guides 1. Get in small groups (2-4) 2. Introduce yourselves 3. Look at images: 1. http://bit.ly/devsignercon_semantics_1 2. http://bit.ly/devsignercon_semantics_2 4. Come up with some widgets: you need a name! 5. We’ll share in 5 minutes
 (look for the raised hands)
92. @foliosus http://bit.ly/devsignercon-style-guides 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 5 minutes
93. @foliosus http://bit.ly/devsignercon-style-guides SHARING TIME ‣ Reshuffle the groups a bit ‣ Re-introduce yourselves ‣ Talk about the widgets you came up with ‣ Convince each other that you chose wisely (or poorly!)
94. @foliosus http://bit.ly/devsignercon-style-guides WHY GO TO ALL THIS TROUBLE??
95. @foliosus http://bit.ly/devsignercon-style-guides ROAD MAP It’s all about rules Typography Living style guides The inevitable redesign
96. THE REDESIGN
 IS INEVITABLE https://flic.kr/p/dY8PZF
97. @foliosus http://bit.ly/devsignercon-style-guides NOBODY WANTS PLANNED OBSOLESCENCE
98. @foliosus http://bit.ly/devsignercon-style-guides OUR RECORD:
 1 PERSON, 10 DAYS* *your mileage may vary
99. THANK YOU! @foliosus https://flic.kr/p/bhyT8B bit.ly/devsignercon-style-guides