README.md

CSS-in-JavaScript Style Guide

A mostly reasonable approach to CSS-in-JavaScript

Table of Contents

1. Naming
2. Ordering
3. Nesting
4. Inline

Naming

• Use camelCase for object keys (i.e. "selectors").

  Why? We access these keys as properties on the styles object in the component, so it is most convenient to use camelCase.

  // bad
  {
    'bermuda-triangle': {
      display: 'none',
    },
  }
  
  // good
  {
    bermudaTriangle: {
      display: 'none',
    },
  }

• Use an underscore for modifiers to other styles.

  Why? Similar to BEM, this naming convention makes it clear that the styles are intended to modify the element preceded by the underscore. Underscores do not need to be quoted, so they are preferred over other characters, such as dashes.

  // bad
  {
    bruceBanner: {
      color: 'pink',
      transition: 'color 10s',
    },
  
    bruceBannerTheHulk: {
      color: 'green',
    },
  }
  
  // good
  {
    bruceBanner: {
      color: 'pink',
      transition: 'color 10s',
    },
  
    bruceBanner_theHulk: {
      color: 'green',
    },
  }

• Use selectorName_fallback for sets of fallback styles.

  Why? Similar to modifiers, keeping the naming consistent helps reveal the relationship of these styles to the styles that override them in more adequate browsers.

  // bad
  {
    muscles: {
      display: 'flex',
    },
  
    muscles_sadBears: {
      width: '100%',
    },
  }
  
  // good
  {
    muscles: {
      display: 'flex',
    },
  
    muscles_fallback: {
      width: '100%',
    },
  }

• Use a separate selector for sets of fallback styles.

  Why? Keeping fallback styles contained in a separate object clarifies their purpose, which improves readability.

  // bad
  {
    muscles: {
      display: 'flex',
    },
  
    left: {
      flexGrow: 1,
      display: 'inline-block',
    },
  
    right: {
      display: 'inline-block',
    },
  }
  
  // good
  {
    muscles: {
      display: 'flex',
    },
  
    left: {
      flexGrow: 1,
    },
  
    left_fallback: {
      display: 'inline-block',
    },
  
    right_fallback: {
      display: 'inline-block',
    },
  }

• Use device-agnostic names (e.g. "small", "medium", and "large") to name media query breakpoints.

  Why? Commonly used names like "phone", "tablet", and "desktop" do not match the characteristics of the devices in the real world. Using these names sets the wrong expectations.

  // bad
  const breakpoints = {
    mobile: '@media (max-width: 639px)',
    tablet: '@media (max-width: 1047px)',
    desktop: '@media (min-width: 1048px)',
  };
  
  // good
  const breakpoints = {
    small: '@media (max-width: 639px)',
    medium: '@media (max-width: 1047px)',
    large: '@media (min-width: 1048px)',
  };

⬆ back to top

Ordering

• Define styles after the component.

  Why? We use a higher-order component to theme our styles, which is naturally used after the component definition. Passing the styles object directly to this function reduces indirection.

  // bad
  const styles = {
    container: {
      display: 'inline-block',
    },
  };
  
  function MyComponent({ styles }) {
    return (
      <div {...css(styles.container)}>
        Never doubt that a small group of thoughtful, committed citizens can
        change the world. Indeed, it’s the only thing that ever has.
      </div>
    );
  }
  
  export default withStyles(() => styles)(MyComponent);
  
  // good
  function MyComponent({ styles }) {
    return (
      <div {...css(styles.container)}>
        Never doubt that a small group of thoughtful, committed citizens can
        change the world. Indeed, it’s the only thing that ever has.
      </div>
    );
  }
  
  export default withStyles(() => ({
    container: {
      display: 'inline-block',
    },
  }))(MyComponent);

⬆ back to top

Nesting

• Leave a blank line between adjacent blocks at the same indentation level.

  Why? The whitespace improves readability and reduces the likelihood of merge conflicts.

  // bad
  {
    bigBang: {
      display: 'inline-block',
      '::before': {
        content: "''",
      },
    },
    universe: {
      border: 'none',
    },
  }
  
  // good
  {
    bigBang: {
      display: 'inline-block',
  
      '::before': {
        content: "''",
      },
    },
  
    universe: {
      border: 'none',
    },
  }

⬆ back to top

Inline

• Use inline styles for styles that have a high cardinality (e.g. uses the value of a prop) and not for styles that have a low cardinality.

  Why? Generating themed stylesheets can be expensive, so they are best for discrete sets of styles.

  // bad
  export default function MyComponent({ spacing }) {
    return (
      <div style={{ display: 'table', margin: spacing }} />
    );
  }
  
  // good
  function MyComponent({ styles, spacing }) {
    return (
      <div {...css(styles.periodic, { margin: spacing })} />
    );
  }
  export default withStyles(() => ({
    periodic: {
      display: 'table',
    },
  }))(MyComponent);

⬆ back to top