コンテンツにスキップ
monosus コーディングガイドライン

命名規則

名前を考えるときはその兄弟や親戚や親の名前も考えておきましょう。

正しいスペルの英単語を使用する

CSpellでエラーが出ないようにして下さい。monosus/lint-toolsにも導入されています。

<!-- NG例 -->
 <div class="fullwidth"></div>

エディター上のcspellエラー

略語を使用しない

英語圏で頻出するもの以外は略語、スペルの省略はしません。

省略しても納品は早くなりません。省略しないことでコードの明確さが向上し読み手の時間が最適化されます。
（会話の中での略語にも同じことが言えるでしょう）

英語圏で頻出するものの例

  • attr (attribute)
  • nav (navigation)
  • res (response)
  • arg (argument)
  • err (error)
  • auth (authentication)
  • opt (option)
  • init (initialize)

…

ざっと書き出してみましたが、変数名に使えるものは少なそうです。独自の省略形を使用するのであればそのままの英単語を使用してください。

  • btn → buttonとしましょう
  • txt → textとしましょう
  • ttl → titleとしましょう

意味が伝わらない命名を避ける

数字の羅列やハッシュ値のようなもの、複数単語の頭文字をつなげただけなど、レビューや第三者が内容を推察できないものは避けてください。

プログラムによって独自に生成されるハッシュ値などは許容されますが、後工程にシステムの組み込みなどがある場合は制作環境のキャッシュによってハッシュ値が変更になるタイミンがあることを憂慮してください。

ローマ字表記を使わない

英単語を使用してください。

ここからは命名が必要になるカテゴリーごとに気をつけるべき点を記載しています。

id属性（HTML）

単語同士のつなぎ方：kebab-case（単語をハイフンで結合）またはPascalCase（単語の先頭を大文字で表記）

プロジェクト内で単語のつなぎ方は揃えてください。ページ中に一度しか登場しないためシンプルな命名を心がけます。 ランドマーク名やそのコンテンツの文脈で命名することが望ましいでしょう。（例：#header、#table-of-contents）

PascalCaseを採用した場合、グローバル変数として容易に取得できてしまうことを考慮してください。（kebab-caseだと安全というわけではありませんが、悪意のないバグの発生は抑えられるでしょう）

data属性（HTML）

単語同士のつなぎ方：kebab-case

用途としては

  • JavaScriptのフック
  • CSSのバリアント

などが考えられます。
data属性には値も格納できるため、ある程度使用方法のルールをプロジェクト内で決めましょう。以下を参考にして、あまりユニークなものが増えすぎないようにしてください。

data属性の命名例

単語名用途使用例
data-scheme,data-scheme-type構造化データを挿入するフック<main data-scheme="article">
data-[uiName],data-js-[uiName]JavaScriptで対象要素を取得するためのフック<details data-accordion="faq">
data-[uiName]-variantCSSでコンポーネントのバリアントをスタイルするためのフック<article class="info-card" data-card-variant="high-priority">
data-state=“stateName”スタイルガイドなどでhoverやfocusスタイルを適用させるためのフック<a class="link-button" data-state="hover">

CSS変数

単語同士のつなぎ方：kebab-case

CSS変数はかなりの数を使用することになります。一定のルールを定めておきましょう
また、このセクションでは命名ルールとともに使用方法にも言及します。

グローバルCSS変数

rootやhtml、bodyで宣言するデザイントークンとしての変数です。

-- + 種別 + 単位または値

で表現します。場合によってはprefixを使用してください。（例：--system-color-black）

--color-white: #fff;
--color-green-rgb: 0 128 0;
--space-xxs: 4px;
--space-xxs-relative: 0.25rem;
--rounded-xs: 4px;


/* ボーダーはショートハンドを許容しているので色味について変数を再代入しつつ使用します */
--system-border-base: 1px solid var(--color-gray);


/* ⛔Bad */
/* グローバルCSS変数では部位の色やサイズを直接指定するのは控えます */
--border-gray: #ccc;

スコープドCSS変数

コンポーネントで使用する変数です。コンポーネントで直接グローバル変数を使用するのは控えます。 コンポーネント内でスコープドCSS変数を宣言し、そこにグローバルCSS変数（デザイントークン）を代入します。
これによって、CSS変数の再代入によってスタイリングを容易に変更できるようになると同時に、デザイントークンから逸脱したスタイルの混入を抑止します。

-- + コンポーネント名 + プロパティ

で表現します。

/* 使用例 */
button {
    --button-bg: var(--color-green-rgb);
    --button-bg-opacity: 1;


    background-color: rgb(var(--button-bg) / var(--button-bg-opacity))


    &:hover {
        --button-bg-opacity: 0.5;
    }


    &[data-variant*="primary"] {
        --button-bg: var(--color-brand-primary);
    }


    &[data-variant*="edge"] {
        --button-round: 0;
    }
}

クラス名（CSS）

単語同士のつなぎ方：kebab-case

基本的なクラス命名

コンテンツ上の役割や特徴 + UIの名称等をおすすめします。

prefixは必要な理由が明確でなければ付ける必要はありません。

.header,.footer {/* ... */}
.image-card {/* ... */}
.image-card > header {/* ... */}
.image-card > img {/* ... */}
.image-card > footer {/* ... */}
.image-card > footer > a {/* ... */}
.warning,.warning-box {/* ... */}

.image-cardの一例

直下セレクター（>）などを使用することも考えられます。

クラス名image-cardのデザインイメージ

<article class="image-card">
  <img src="..." alt="..." width="..." height="..." decode="async" laoding="lazy" >
  <h3>タイトル</h3>
  <p>テキスト テキスト テキスト...</p>
  <a hred="...">リンク</a>
</article>

良いクラス名のための考え方

タグにスタイルをつけるためにクラスは使用せず、コンポーネントとしての大きさでクラス名を使用しましょう。

プレゼンテーションなクラス名はNGです。（NG例：.border-orange、.more-margin、.text-pink-500など）
クラス内にサイズ表記が入るものも控えましょう。（NG例：.media-card-xs、.card-list.-cols-3）

BEMやFLOCSSよりもコンポーネントのルートにシンプルなクラス名（スコープドクラス）を使用することを推奨します。

CSSの章でも言及していますが、スコープドクラスから直接参照できる要素にクラス名は不要です。
なくても機能するものをわざわざ記述する必要はありません。
必要な場合は必要なだけクラス属性を記述してください。

クラス名で構造を想起させるものも控えます。（NG例：.*-container、.*-wrapper、.*-inner）
これは無用なdiv要素を挿入しないための工夫です。

マルチクラスは推奨しません。バリアントを使用する場合はdata属性などを検討してください。

/* バリアントの例 塗りつぶしが無いゴーストボタン     */
.button { /* ... */}
.button[data-button-variant="ghost"] {
    --button-fill:transparent;
    --button-color:currentColor;
    --button-stroke-color:var(--color-strong-gray)
}

変数名（JavaScript）

単語同士のつなぎ方：camelCase（単語の先頭を大文字で表記、最初の単語のみ小文字）

名詞を使用します。状態や可能性を含めたい場合は動詞を名詞の前につけます。

const number
const selectedNumber

クラス名（JavaScript）

単語同士のつなぎ方：PascalCase

関数名（JavaScript）

単語同士のつなぎ方：camelCase

イベントリスナーのコールバックは

handle + 発火する対象など + イベント名

とします。モジュール内で発火要素が自明の場合は

handle + イベント名

でも構いません。

document.addEventListener('click','handleSubmitButtonClick)

定数（JavaScript）

単語同士のつなぎ方：CONSTANT_CASE（大文字の名詞をアンダースコアで結合）

import.meta.env.PUBLIC_API_TOKEN

ディレクトリ名（納品時）

単語同士のつなぎ方：kebab-case（場合によってはsnake_case（単語をアンダースコアで結合））

  • 半角英数を使い、そのフォルダの内容がわかるようにする
  • ナンバリングする際はゼロパディングを施してください（例：sys1ではなくsys01など管理番号が増えた場合に対応しておく）
  • 先頭には「-（ハイフン）」「_（アンダースコア）」を使用しないでください
  • スペースは使用しないでください