How to Build a Page From Scratch

1. Create a HAML view file wherever needed.

2. Declare a 'body_class' at the top to create your CSS sandbox.

   You can also add multiple classes to mix in shared styles from other pages.
   
   We usually recommend adding things to the global /library at this point, but not always (like for logged out pages with specific stuff).

   - content_for :body_class, 'my-page my-page-shared-components'

3. Create an SCSS page file in `app/assets/stylesheets/pages/**somewhere**`

4. Open body class in SCSS and put custom page CSS inside of it.

   Now you don't have to worry about your stuff leaking to other pages.

   .my-page { .some-page-specific-components { // WHOO } }

Some Principles

• Try not to nest SCSS declarations

  Keep components flat to avoid fighting the cascade of inherited styles.

  .my-page { .component { } .component__child { } .component__child__child { } }

• Stick to BEM notation to describe your creations

  Conventions increase scannability of code. Adherence reduces friction for other developers.

  But of course, if you oppose a piece of the convention, we welcome PRs that demonstrate a better way.

• Choose the right abstraction for the right lifecycle stage of your page

  See the guide below for your options.

How to choose the right HTML/CSS abstraction.

Hired frontend is designed to "go with the flow" of code growth rather than fight it. Let's walk through a typical page's lifecycle and the abstractions we'd choose at each.

1. Start small, with HTML only and no CSS

   Primitive building blocks and existing copy + design come in handy.

   • Layouts
   • Helpers
   • Typography
   • Boxes
   .box.box--red.xs-p2.xs-text-center %h4 Here's some great content.

2. As repetition of markup begins to appear in file, generalize into page specific components.

   Create or find the existing page CSS sandbox for your HAML file.

   .my-box %h4 Here's some great content. .my-page { .my-box { background-color: $brand-red; color: $brand-black; padding: 2 * $base-spacing-unit; text-align: center; } }

3. If using components on 3+ pages, add to /library to document.

   Notice how late in the cycle we add it to /library. By not documenting experimental product, we empower our teams to iterate on code nuance and avoid premature abstraction.

   There is a simple heuristic to determine when it’s time to document a thing:

   When a component is being used on 3 pages or more, it’s time for it to live here.