Tweet
Tweet

Slide 1

Slide 1 text

‹#› © 2015 T7 July 24, 2015 October 20, 2015 Node.js and Style Guides

Slide 2

Slide 2 text

Nathan Smith! Principal Front-End Architect Mundi Morgado! Director of Front-End Architecture Introductions

Slide 3

Slide 3 text

! Github Repo:! http://github.com/t7/style-guide-example! ! Slides:! http://j.mp/node-style-guide! ! Mundi Morgado! @mundizzle! ! Nathan Smith! @nathansmith

Slide 4

Slide 4 text

! TandemSeven! Developers :) !

Slide 5

Slide 5 text

We Begin with a Simple Assumption…! ! People are not mind readers. We are visual in nature. We tend not to follow instructions well.

Slide 6

Slide 6 text

We do not like being told what to do, but we do like knowing how things fit together.! ! (Even if we end up taking them apart and making them our own.)

Slide 7

Slide 7 text

We Enjoy Knowing the "Why" of Design

Slide 8

Slide 8 text

Overview • What is a style guide?! • Examples of style guides! • Rolling your own framework! • Using NPM and Webpack! • Using ES6 and React! • Using PhantomJS! • DEMO! :)

Slide 9

Slide 9 text

What Is a! Style Guide?

Slide 10

Slide 10 text

What a Style Guide May Contain! ! It is about design governance and code standards.! ! What we mean by that is:! ! • No more rogue agents, shooting from the hip with unique snowflake designs, or developers building one-off widgets in code.
 • Everything in a project should exist for a reason, and its purpose should be documented accordingly.
 • This allows for easier and quicker onboarding, where someone can refer back to established patterns and code conventions.
 • It gives you a defensive point reference, in case implementation goes awry. It's a "last known good" state of UI development.! ! (Design coworker Brandy Taylor coined the term "Design Governance.")

Slide 11

Slide 11 text

No More One Offs

Slide 12

Slide 12 text

Managing Expectations! ! ! “The movie opens with a gentleman in a jacket, sporting a mustache…”

Slide 13

Slide 13 text

Managing Expectations: Perception

Slide 14

Slide 14 text

Managing Expectations: Perception vs. Reality

Slide 15

Slide 15 text

In Addition to Design, We Also Document! ! • Accessibility expectations, with a tie-in to SEO to "sell" it.! ! • AJAX does not mean "Accessibility Just Ain't eXciting."! ! • Browser requirements (January 12, 2016 = R.I.P. IE8).! ! • Best practices:
 • Responsive design, explanation and breakpoints.
 • What we will or will not attempt to achieve outside of CSS.
 • Border-radius, box-shadow, gradients, opacity, etc.
 • Non-native form controls. Styling is okay, but recreating something the browser gives you "for free" is not.

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

No content

Slide 18

Slide 18 text

Really, your style guide can contain anything! :) http://thosewhowanderblog.com/2013/01/15/bus2alps-loves-chuck-norris/

Slide 19

Slide 19 text

Examples of! Style Guides

Slide 20

Slide 20 text

No content

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

In Summary Just use Bootstrap.! Thanks for coming! :)

Slide 23

Slide 23 text

No content

Slide 24

Slide 24 text

Clarification! ! There is nothing inherently wrong with using a third party
 library or framework (that is half our job), assuming that…
 ! • The library or framework that you are using
 solves a problem you actually have.
 • You are not "solutioneering," attempting to use a
 tool designed to solve other people's problems.! ! • You are using it as a "tool," not a "crutch."! ! ! The more invested you are in a "kitchen sink" framework,
 especially if it lacks extensibility, the harder it is to adapt
 to change over the lifetime of a given app or product.

Slide 25

Slide 25 text

http://legoquestkids.blogspot.com/2011/02/30-pieces-quest-34.html One Size Does Not Fit All. Never Use Absolutes.

Slide 26

Slide 26 text

No content

Slide 27

Slide 27 text

No content

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

No content

Slide 30

Slide 30 text

No content

Slide 31

Slide 31 text

No content

Slide 32

Slide 32 text

No content

Slide 33

Slide 33 text

Or, You Could Always Just

Slide 34

Slide 34 text

Rolling Your! Own Framework

Slide 35

Slide 35 text

How We Made Our Style Guide Framework http://nodejs.org

Slide 36

Slide 36 text

How We Made Our Style Guide Framework http://npmjs.org

Slide 37

Slide 37 text

How We Made Our Style Guide Framework https://en.wikipedia.org/wiki/Blood,_Sweat_%26_Tears

Slide 38

Slide 38 text

Note: We Do Not Recommend Rewriting Your Framework Three Weeks Before a Presentation! ! September 25th, 2015! ! Nathan: "When you get back from Burning Man, let's start working on our Front Porch slides."! ! Mundi: "Actually, why don't we go ahead and rewrite it using React on the client and server."! ! Nathan: O_o

Slide 39

Slide 39 text

(Nathan handled this idea gracefully, of course.)

Slide 40

Slide 40 text

October 1st, 2015! ! We officially started cranking on the new style guide. (╯°□°)╯︵ ┻━┻

Slide 41

Slide 41 text

Our Requirements for ISG v2! ! • Statically generated.! • Portable.! • Server agnostic.! • Zip-able (can be sent as flat-file).! ! • Stays fresh.! • Can be built from the live app's codebase.! • App should not "know" about the style guide.

Slide 42

Slide 42 text

Our Requirements for ISG v2! ! • Contains brand standards.! • Has room to grow.! • Can have non-dev contributors.! ! • Automated listing of unique patterns.! • Live working UI.! • Code examples: JavaScript and HTML.! ! • Houses screenshots and technical specs.

Slide 43

Slide 43 text

Used in Both v1 and v2 • Lodash.js: data manipulation.! • Glob: file/directory globbing.! • FS-Extra: file system utilities.! • PhantomJS: for screenshots.

Slide 44

Slide 44 text

What Changed from v1 to v2 • Handlebars: JS templating.! • JSHint: JS validation.! • Sass or flat-file CSS.! • Highlight.js: syntax coloring.! • YAML: for metadata.! ———! • Express: dev server.! • Socket.io: live reloading.! • Chokidar: file watching.! • Async: task automation. • React: JS templating.! • Standard: JS validation.! • Sass/CSS and PostCSS.! • Prism.js: syntax coloring.! • JS/JSON: for metadata.! ———! • Webpack: dev server.! • ES6 to ES5 conversion.! • JS module loading.! • NPM: task automation.

Slide 45

Slide 45 text

Using NPM! and Webpack

Slide 46

Slide 46 text

No content

Slide 47

Slide 47 text

Example NPM package.json ! { "scripts": { "test": "standard", "prestart": "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }

Slide 48

Slide 48 text

Example NPM package.json ! { "scripts": { "test": "standard", "prestart": "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }

Slide 49

Slide 49 text

Example NPM package.json ! { "scripts": { "test": "standard", "prestart": "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }

Slide 50

Slide 50 text

Example NPM package.json ! { "scripts": { "test": "standard", "prestart": "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }

Slide 51

Slide 51 text

Example NPM package.json ! { "scripts": { "test": "standard", "prestart": "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }

Slide 52

Slide 52 text

Gotchas with NPM! ! • We love that using NPM for task automation removes the need to use a task runner like Grunt or Gulp.! ! • However, chaining together commands with NPM scripts can get hairy. There are tradeoffs either way.! ! • Closer to the metal, but more manual curation.

Slide 53

Slide 53 text

Gotchas with NPM! ! Cross platform portability…! ! For example, {"clean": "rm -r ./build"} will not work on Windows.! ! Instead, use something like Trash-CLI.! ! It abstracts this functionality across platforms.! ! https://github.com/sindresorhus/trash-cli

Slide 54

Slide 54 text

Example of Trash-CLI ! // Before. {"clean": "rm -r ./build"} ! ! // After. {"clean": "trash ./build"}

Slide 55

Slide 55 text

Things to Consider! ! • If it suits your project's needs, using Grunt or Gulp can help ease the burden of automation.! ! • Ultimately, both Gulp and Grunt use Node under the hood anyway.! ! • Using NPM scripts is like an "API" to your build automation. Even if you are using Grunt or Gulp, you can map tasks to package.json too.

Slide 56

Slide 56 text

Using ES6! and React

Slide 57

Slide 57 text

No content

Slide 58

Slide 58 text

I Will Admit… React is awesome. I was basically super wrong.! ! Over the years, I have only found a short list
 of concepts to be exciting in web development.! ! • CMS powered sites.! • jQuery.! • Sass.! • React.

Slide 59

Slide 59 text

ECMAScript 6 is Weird (in a Familiar Way) The way we are using React is…! ! • ES6 classes, transpiled to ES5 (via Babel).! • JSX ("HTML" in JS), which Nathan thought he would dislike.! • "Standard" for our JS linter.! • ASI: Automatic Semicolon Insertion – Don't kill us!! • Otherwise, it has generally agreeable conventions.! ! Note: ES6 and JSX feel different enough that going ASI (too) was not actually that big of a stretch. MAKE NEW ALL THE THINGS.

Slide 60

Slide 60 text

No content

Slide 61

Slide 61 text

No content

Slide 62

Slide 62 text

No content

Slide 63

Slide 63 text

Using React on the Server – aka "isomorphic"! – aka "universal" – aka "cool kids" • Create JSX "layout" components.
 • Then, using Node…
 • Use webpackRequire() to load the template and
 resolve dependencies: CSS, Markdown, images, etc.
 • Use ReactDOMServer.renderToStaticMarkup()
 to process the template and return HTML.
 • Save the rendered HTML output to disk.

Slide 64

Slide 64 text

No content

Slide 65

Slide 65 text

Using PhantomJS to! Create Screenshots

Slide 66

Slide 66 text

No content

Slide 67

Slide 67 text

Our Approach to Creating Screenshots! ! • We create a PhantomJS script to iterate through a list of paths, taking a screenshot of each at mobile, tablet, and desktop widths.! ! • We generate a list of full-page screenshots that are linked to each actual "application" screen.

Slide 68

Slide 68 text

PhantomJS Gotchas! ! • A server must be running for phantom to be able to access the pages you want to screenshot. Keep your server on!! ! • We wanted to use the awesome PageRes library. However, it ships with PhantomJS 1.x which uses an old version of WebKit. This has poor support for CSS3, making our screenshots look less than ideal.
 
 https://github.com/sindresorhus/pageres

Slide 69

Slide 69 text

PhantomJS Gotchas! ! • PhantomJS 2.x is not easily installed via NPM (in our experience).! ! • You have to manually download and install PhantomJS yourself, which makes automation difficult. It is not as easy as:
 "npm install ..."! ! • Activity on the project seems to have slowed.! ! • In the future, we may look at using SlimerJS (based on Firefox).

Slide 70

Slide 70 text

PhantomJS Pro Tip™! ! We are adding to the document, so that approaches like having a "sticky footer" don’t jack with the page's natural height. Basically, forcing something other than the tag to scroll will confuse Phantom.! ! You can manually add this to the HTML tag (or via console) as you build pages, to check what PhantomJS will "see" when it goes to screenshot each page. This approach allows you to (de-)target Phantom via CSS.

Slide 71

Slide 71 text

No content

Slide 72

Slide 72 text

No content

Slide 73

Slide 73 text

Okay, Let's Dig! Into This Demo

Slide 74

Slide 74 text

No content

Slide 75

Slide 75 text

No content

Slide 76

Slide 76 text

No content

Slide 77

Slide 77 text

No content

Slide 78

Slide 78 text

No content

Slide 79

Slide 79 text

No content

Slide 80

Slide 80 text

No content

Slide 81

Slide 81 text

! Github Repo:! http://github.com/t7/style-guide-example! ! Slides:! http://j.mp/node-style-guide! ! Mundi Morgado! @mundizzle! ! Nathan Smith! @nathansmith