Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Node Style Guide

Node Style Guide

Talk from Front Porch 2015, on using Node and React to make an interactive style guide.

A video of our talk is available here…

https://youtu.be/SoEPoww5BdA

Nathan Smith

October 20, 2015
Tweet

More Decks by Nathan Smith

Other Decks in Programming

Transcript

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  4. !
    TandemSeven!
    Developers :)
    !

    View full-size slide

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

    View full-size slide

  6. 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.)

    View full-size slide

  7. We Enjoy Knowing the "Why" of Design

    View full-size slide

  8. 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! :)

    View full-size slide

  9. What Is a!
    Style Guide?

    View full-size slide

  10. 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.")

    View full-size slide

  11. No More One Offs

    View full-size slide

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

    View full-size slide

  13. Managing Expectations: Perception

    View full-size slide

  14. Managing Expectations: Perception vs. Reality

    View full-size slide

  15. 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.

    View full-size slide

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

    View full-size slide

  17. Examples of!
    Style Guides

    View full-size slide

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

    View full-size slide

  19. 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.

    View full-size slide

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

    View full-size slide

  21. Or, You Could Always Just

    View full-size slide

  22. Rolling Your!
    Own Framework

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  26. 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

    View full-size slide

  27. (Nathan handled this idea gracefully, of course.)

    View full-size slide

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

    View full-size slide

  29. 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.

    View full-size slide

  30. 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.

    View full-size slide

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

    View full-size slide

  32. 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.

    View full-size slide

  33. Using NPM!
    and Webpack

    View full-size slide

  34. 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"
    }
    }

    View full-size slide

  35. 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"
    }
    }

    View full-size slide

  36. 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"
    }
    }

    View full-size slide

  37. 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"
    }
    }

    View full-size slide

  38. 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"
    }
    }

    View full-size slide

  39. 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.

    View full-size slide

  40. 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

    View full-size slide

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

    View full-size slide

  42. 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.

    View full-size slide

  43. Using ES6!
    and React

    View full-size slide

  44. 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.

    View full-size slide

  45. 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.

    View full-size slide

  46. 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.

    View full-size slide

  47. Using PhantomJS to!
    Create Screenshots

    View full-size slide

  48. 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.

    View full-size slide

  49. 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

    View full-size slide

  50. 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).

    View full-size slide

  51. 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.

    View full-size slide

  52. Okay, Let's Dig!
    Into This Demo

    View full-size slide

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

    View full-size slide