Ragate HTML/CSS/Vue.js Style Guide

Ragate CSS スタイルガイド

社内向けのドキュメントですが、ご質問やご意見等あればコメント大歓迎です！

はじめに

Ragate株式会社では、エンジニアを募集しています！
https://recruit.ragate.co.jp/

スタイルガイドのガイド

• 規約で縛りすぎない（エンジニア上級者にとって細かすぎる規約は足枷でしかなく、開発スピードが落ち、やる気も損ねるため）
• 各項目には MUST か SHOULD をラベリングする
• MUST は必ず守る規約
• SHOULD はできれば守ってほしい推奨項目
• なるべく例をコードで書き示す
• 個人的な好みではなく合理性を追求する

セミコロン

MUST 宣言の後ろに毎回セミコロン(;)を付ける。

/* Bad */
.hoge {
  display: flex;
  width: 1000px
}

/* Good */
.hoge {
  display: flex;
  width: 1000px;
}

インデント

SHOULD Tabではなくスペース2つで統一する

.hoge {
  color: #fff;
}

SHOULD block, list, table要素は改行し、その子要素にはインデントを入れる。

<blockquote>
  <p><em>Hello</em>, World.</p>
</blockquote>

<ul>
  <li>hoge
  <li>fuga
  <li>piyo
</ul>

<table>
  <thead>
    <tr>
      <th>ほげ</th>
      <th>ふが</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>hoge</td>
      <td>fuga</td>
    </tr>
  </tbody>
</table>

セレクタ

MUST idは使用せず（JavaScriptでグローバル汚染するため）、classを使う

/* Bad */
#hoge {
  color: #fff;
}

/* Good */
.hoge {
  color: #fff;
}

MUST リセット以外の目的ではHTMLタグ名でスタイル定義せず、classを使う

/* Bad */
div {
  color: #fff;
}

/* Good */
.container {
  color: #fff;
}

/* Good（リセット目的ならOK） */
body {
  margin: 0;
}

命名

SHOULD クラス名やコンポーネント名は、見た目ではなく意味を表す単語で命名する

/* Bad */
.margin20 {}
.left {}
.sideMenu {}

/* Good */
.pageHeader {}
.globalMenu {}
.buttonSubmit {}

SHOULD クラス名やコンポーネント名は略さない（略しても意味が伝わるならOK）

/* Bad */
.fvc {}

/* Good */
.firstViewContainer {}

MUST Vueコンポーネントの一番外側の要素にはプロジェクト全体で被らないユニークな名前をつける

Bad（一番外側の要素はスコープに入らないため汎用的な命名は危険）

MainContainer.vue

<template>
  <div class="container">
    ...
  </div>
</template>
<style lang="postcss" scoped>
.container {

}
</style>

Good（パスカルケースで命名したコンポーネント名をそのまま流用するのが一番楽。）

MainContainer.vue

<template>
  <div class="MainContainer">
    ...
  </div>
</template>
<style lang="postcss" scoped>
.MainContainer {

}
</style>

インライン

MUST 特別な理由がない限りインラインスタイルは書かない

<!-- Bad -->
<div style="margin: 20px"></div>

<!-- Good -->
<div class="mainContents"></div>

共通化

MUST サイト全体で同じ色を何度も使う場合には変数（CSS Custom Properties）を定義する

:root {
  --main-color: #ff0099;
}
.hoge {
  color: var(--main-color);
}

MUST CSSの共通化は変数定義だけに留め、基本的にはVue.jsのComponent（Scoped CSS）を使って共通化する

以下Bad例

index.vue

<template>
  <div>
    <div class="pageContainer">
      <div class="pageHeader">
        ヘッダー
      </div>
      <div class="pageContents">
        内容
      </div>
      <div class="pageFooter">
        フッター
      </div>
    </div>
  </div>
</template>

common.css

.pageContainer {
  
}
.pageHeader {
  
}
.pageContents {
  
}
.pageFooter {
  
}

以下Good例

index.vue

<template>
  <div>
    <PageContainer>
      <PageHeader>
        ヘッダー
      </PageHeader>
      <PageContents>
        内容
      </PageContents>
      <PageFooter>
        フッター
      </PageFooter>
    </PageContainer>
  </div>
</template>

<script>
import PageContainer from '@/components/common/PageContainer'
import PageHeader from '@/components/common/PageHeader'
import PageContents from '@/components/common/PageContents'
import PageFooter from '@/components/common/PageFooter'
export default {
  components: {
    PageContainer,
    PageHeader,
    PageContents,
    PageFooter,
  },
}
</script>

PageContainer.vue

<template>
  <div class="PageContainer">
    <slot />
  </div>
</template>

<style lang="postcss" scoped>
.PageContainer {

}
</style>

postcss-preset-env

SHOULD 知名度の低い機能をあまり多用しない（初学者が混乱するため）

MUST 擬似クラスや疑似要素はネストして指定する

/* Bad */
.hoge {
  display: flex;
}
.hoge:hover {
  opacity: 0.5;
}
.hoge:after {
  content: "";
  display: block;
}

/* Good */
.hoge {
  display: flex;
  &:hover {
    opacity: 0.5;
  }
  &:after {
    content: "";
    display: block;
  }
}

あとがき

社内向けのドキュメントですが、ご質問やご意見等あればコメント大歓迎です！

また、Ragate株式会社では、エンジニアを募集しています！（2回目）
採用サイトもかなりこだわっているので是非一度ご覧になってみてください！
https://recruit.ragate.co.jp/