Skip to content

Instantly share code, notes, and snippets.

@kevnk

kevnk/00-Premise.md

Last active August 29, 2015 14:20
Show Gist options
  • Save kevnk/ee11514d12249d94ed9b to your computer and use it in GitHub Desktop.
Save kevnk/ee11514d12249d94ed9b to your computer and use it in GitHub Desktop.
Download ZIP
Coding Style Guide
Raw
00-Premise.md

Solved

Let me start with the solution: ReactJS includes the styles inline and/or in the same file as the elements they're being used on. This removes my frustrations with multiple people working on the same SASS/LESS project.

So this is only for projects that don't follow the methodology above.

A couple frustrations

  1. Classes and IDs (more often than not) need to communicate and describe the styles they are setting, not describe what/where the element is.

  2. SO Too many different conventions! -lg -large f-size-xlarge padding-top-10 are all inconsistent! No one knows what variables to use unless you make them up yourself—at which point you may as well forget about using variables if working with multiple people.

Objective

Set a standard for variable/class/ID naming that helps communicate what the styles are actually doing

Raw
10-HTML.md

HTML

  • /html or /templates are the default directory names for html files
  • 4 space indentation for code
  • Use html tags where appropriate
    • <main/>, <nav/>, <header/>, <footer/>, <section/>, <article/>

Element Attributes

  • Always use double quotes
  • Prefix custom attributes with data-[uuid] where [uuid] is a unique identifier for the application, i.e. data-cm-content for CaseManager
  • Attribute listing priority (which attributes to put first)
    1. type when applicable
    2. id
    3. class
    4. inherit attributes
    5. event-related attributes
    6. custom data-attributes

IDs and Classes

  • IDs are snake_case
  • Classes are dash-case
  • Prefer class names over IDs
    • If you use an ID, consider including a relevant class
Utility Classes before Semantic Classes
  • Especially when working with a template and less file with each View file, markup should communicate styles and not semantics.
<!-- Good -->
<div class="select-organization-view card">
    <ul class="ul-unstyled">
    {{~it.organizations :org:itemIndex}}
        <li class="tile tile-nav">{{=org.name}}</li>
    {{~}}
    </ul>
</div>

<!-- Bad -->
<div class="org-wrapper">
    <ul class="org-list">
        <li class="org-item"></li>
    </ul>
</div>

<!-- Overkill -->
<div class="bg-white pad15 mar20">
    <ul class="noStyle noMargin noPadding">
        <li class="bg-white arrow-after bb-gray"></li>
    </ul>
</div>

The reasons to use the first example are:

  1. No one looks at classes for semantics. Chances are you know what is in that div by what content is being output. Classes should describe its element's styles. Make life easier on yourself
  2. (whynotboth) Because it gets bloated and then people start making styles with the semantic ones and it gets gross.
  3. How do I make unique stuff? Don't create a billion utilities. Notice the outer-most div in has a unique class (the dash-case version of the views name). You can next your styles accordingly. This also makes it easier to find templates, views, and styles.
Common Class Use-Cases

If you must have some semantic-type classes, use these common patterns:

  • Use -wrapper suffix when extra wrapping element is needed for styling purposes
  • Use -list suffix for list (with nav elements as the exception)
  • Use -item suffix for list of items

Form Attributes

  • Always use the most specific input type (more info)
    • search
    • email
    • url
    • tel
    • number
    • range
    • date
    • month
    • week
    • time
    • datetime
    • datetime-local
    • color
    • text
    • submit
<body>
    <div class="page-wrapper">
        <div class="header-wrapper">
            <header id="header">
                <nav id="nav">
                    <a class="nav-item" href="/home">Home</a>
                    <a class="nav-item" href="/about">About</a>
                    <a class="nav-item" href="/contact">Contact</a>
                </nav>
            </header>
        </div>
        <main id="main" class="container">
            <form action="#">
                <input type="text" id="first_name" class="input-text" />
                <input type="email" id="email" class="input-text" />
                <input type="tel" id="phone_number" class="input-text" />
                <button type="submit">Send</button>
            </form>
        </main>
        <div class="footer-wrapper">
            <footer id="footer">
                <nav class="footer-nav col-6">
                    <a class="nav-item" href="/home">Home</a>
                    <a class="nav-item" href="/about">About</a>
                    <a class="nav-item" href="/contact">Contact</a>
                </nav>
                <nav class="footer-nav col-6">
                    <a class="nav-item" href="/home">Home</a>
                    <a class="nav-item" href="/about">About</a>
                    <a class="nav-item" href="/contact">Contact</a>
                </nav>
            </footer>
        </div>
    </div>
</body>
Raw
20-Images.md

Images

  • /images is the default directory for image files
  • Use PNG8 when possible
  • Use sprites when possible
  • Always include retina versions: image_name.png and [email protected]

Image File Naming

  • use snake_case for all image names
  • use icon_ prefix for icons
  • use bg_ prefix for background images
  • use sprite_ prefix for sprites
Raw
30-Fonts.md

Fonts

  • /fonts is the default directory for font files
  • /fonts/icons is the default directory for icon font files
  • First choice is to use fonts from Google Fonts
  • Second choice is to use fonts from FontSquirrel
Raw
40-Scripts.md

Javascript

  • scripts/coffee is the default directory for coffeescript files
  • scripts/js is the default directory for compiled javascript files
  • scripts/bin is the default directory for production-ready javascript files

Coding Style

Raw
50-Styles.md

CSS

  • /styles/less is the default directory for LESS files
  • /styles/css is the default directory for css files that have been compiled from LESS
  • /styles/bin is the default directory for production-ready css files

LESS/SASS

We prefer LESS first, SCSS second (not SASS).

  • use the following LESS files for initial setup
    • variables.less
    • mixins.less
    • utilities.less
  • compile with source maps for easier debugging
  • use a LESS file for each View (or template file if not using views)
    • Name the less file the name of the view

Conventions

First word(s) should describe the CSS rule/property, then add the suffix that describes the variation.

.border-radius-lg {}

Variables use dash-case

Mixins use snake_case

Sizes

Only use the following when using sizes:

  • -xs
  • -sm
  • -md
  • -lg
  • -xl
  • -default which is set to one of the above

Utility Classes

Using three (or so) utility classes (eg. <div class="h2 heading-serif text-align-left padding-sm">) is more descriptive than using a million different unique classes (eg. <div class="leftside-upsell-block-title">). If using more than 3 utility classes, look to create a component class that would be used in other places. If unique to this one element, then make it clear it's unique.

NEVER abbreviate a css property or rule! Use the full property name to avoid confusion:

/* GOOD */
.padding-top-sm {}
.font-size-sm {}
.text-align-left {}

/* BAD */
.pad-top-sm {}
.fz-sm {}
.a-left {}

If we DO use variations, we should use emmet's CSS abbreviations as the standard.

Colors

Descriptive

Use more direct names (eg. red) than vague names (eg. danger):

.color-red {}
.background-green {}

Gray

Always use gray with ay. Never use ey.

Hues

Use color with suffix of percentage number (00-100) to describe hues of the same color (lightest to darkest) where 50% is the name of the color used.

@gray: #666;

@gray-00: lighten(@gray, 50%);
@gray-10: lighten(@gray, 40%); 
@gray-20: lighten(@gray, 30%); 
@gray-30: lighten(@gray, 20%); 
@gray-40: lighten(@gray, 10%); 
@gray-50: @gray; 
@gray-60: darken(@gray, 10%); 
@gray-70: darken(@gray, 20%); 
@gray-80: darken(@gray, 30%); 
@gray-90: darken(@gray, 40%);
@gray-100: darken(@gray, 50%);

For mixed colors (eg. yellow-gray), the first color should be the more color more visible (eg. red-orange for a color that's more red and orange-red that's more orange). Don't use more than two colors in a name. We're not doing Picasso with our CSS. ;)

Headings

Declare tag and heading class:

h1, .h1 {}
h2, .h2 {}

Any alt heading styles should have descriptive classes and begin with heading-:

.heading-sans-serif {}
.heading-serif {}
.heading-italics {}

Buttons

Use the following classes for button:

.button {}
.button.button-lg {}
.button.background-green.color-white {}

Screens and Breakpoints

  • @screen-xs - < 320px eg. watches
  • @screen-sm - 320px - 599px eg. mobile
  • @screen-md - 600px - 1079px eg. tablet
  • @screen-lg - 1080px - 2000px eg. desktop
  • @screen-xl - > 2000px eg. televisions
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment