以前、社内共有と知見をメモするためにWordPressの設計ガイドラインを書きましたが、Webサイト（ページ）のコーディングガイドが必要となってきたので、改めてまとめてみました。
多くのWebサイトを構築した経験値に基づき、特に企業向けのWebページコーディングを、一から行う前提で記述しています。
はじめに
技術やブラウザサポートの進展にあわせて、よりモダンなフレームワークや開発環境が次々と発表されていますが、普通のWebサイト、特に企業向けのサイトに於いては、新しく革新的な技術や設計よりも、以下の方針が往々にしてマッチします。
- 担当者が変わっても編集・変更し易い技術選定
- 拡張・運用していく過程で破綻しない設計
本ガイドは、上記の方針を踏まえたコーディングガイドラインとなります。
本ガイドの最大テーマは、納品物（Webサイトデータ）に一定の品質を担保することです。よって、制作前の決め事・チェック事項もガイドラインに含まれます。反面、直接品質に影響しないHTMLの詳細なルールや、CSS設計方針の詳細指示は省略します。
本ガイドに沿って事前準備や技術選定を行い、他の方々が書いた素晴らしい記事や情報を読んで、高品質なWebページ制作に努めましょう。
コーディング依頼（制作）の前に決めること
コーディングに入る前に、発注・制作双方で以下のすり合わせを行ってください。
すり合わせを行わず、なんとなくで制作を行った場合制作側に迷いが生じ、発注側も何度も修正を依頼することになります。具体的には急なコード変更や、場合によってはデザイン自体の修正が必要なるケースが想定されます。
一方に任せきりにならず、責任を負わせない制作体制がより良い納品物を生む土壌となります。
デザインの確認
このフェーズはデザイン作成の段階で確認する事が最も望ましいです。
- 提供されたデザインが、無理なくHTML化できるかどうか？
- アニメーションや、イベント実行時に表示されるボタンの形状など、静止画ではわからない部分の指示・指定はできているか？
- ページごとによって、見出しやフォントサイズなど、細かいルールが整っているか？
- 仮に整っていない場合、コーディング時に修正・統一してもよいか？
対象ブラウザ・デバイス指定
最も多く使う対応リストとしては、以下のとおりです。なおInternet Explorerへの対応ですが、事前要望としてない限り、11以下の対応は行いません。現在11も要望がない限り対応していませんが、利用ユーザー数によっては配慮が必要になるケースがあります。
デスクトップ端末
- Windows [10]
- Internet Explorer 11
- Microsoft Edge [最新版]
- Mozilla Firefox [最新版]
- Google Chrome [最新版]
- MacOS [最新より1世代前までをサポート]
- Safari [最新版]
- Mozilla Firefox [最新版]
- Google Chrome [最新版]
モバイル端末
- iOS [最新より1世代前までをサポート]
- Mobile Safari
- Android [最新より1世代前までをサポート]
- Google Chrome
- 標準ブラウザ（端末によっては除外）
その他細かい指定のすり合わせを推奨します。
- 大画面ディスプレイで表示した際に表示崩れがあった場合、どうするか
- 動作保証環境以外へは、どのように対応するか
ブラウザ関連の参考
ブレークポイント指定・端末別ファイルの有無
- レスポンシブなのか、PC・SPのみか、それともPCのみなのかを確認
- 端末別にhtmlなどを作る場合、設置ディレクトリなどを確認
例： /sp/, /tablet/... - レスポンシブデザインの場合、各デバイスのブレークポイントの設定を行う
ブレークポイント指示例
| デバイス | ブレークポイント |
|---|---|
| PC | 960px |
| スマートフォン | 768px |
参考
アニメーション指定
アニメーションがどのように動くかの指示を具体的に行ってください。よくコーダーになんとなく任せてしまうケースがありますが、仕様を明確に伝えることで、良い成果物が生まれます。
指示・指定が必要な例
- メインビジュアルなどのキーとなるエリア、スライダーの動き
- パララックス効果を入れるか
- ページスクロール時
- メニュー表示時
- ページ遷移時
アニメーション参考
アニメーション指示を行う上で役立つ参考サイト集です。
開発情報の確認
今でも極稀に「PHPが動かないサーバで、納品直前までPHPで作っていた」など、「？」とリアクションしてしまうようなBADケースを少なからず伺います。無駄な工数や確認事項を減らすためには、出来る限り事前に必須な要件を把握・決定をする必要があります。
主な確認事項
- 使用するWebサーバの選定
- テスト環境の準備
- 事前に想定しているサーバ依存のコード（PHP,DBなど）の動作確認
- Googleのサービスを使う場合、Googleアカウントの発行、準備等
- Webフォント利用の有無
- メールサーバとWebサーバは別なのかどうか（メールのローカル配送問題を参照）
- SSL（https）の有無
- URL正規化の有無（https, http, wwwの統一など）
メタタグ
メタタグはサイトの運用上、必要不可欠な必須情報です。どういったフォーマットで書くか、どう準備するかを事前に決めておくことを推奨します。
- ディスクリプション
- タイトル
- Facebook、Twitterなどのソーシャル用タグの設定
- favicon、iconの設定
なお、メタタグの書き方や推奨字数などの詳細な説明は、当ガイドでは割愛します。
参考
- Googleがサポートしているメタタグ
- The Open Graph protocol
- Optimize Tweets with Cards
- 2018年の Favicon 設定
- 【2018年版】meta descriptionの最適な長さは「300文字」または「グーグル任せ」か | Moz -
担当分け
複数人で中規模以上のWebサイトのコーディングを行う場合、設計のルールや品質のチェックを行うメインコーダー、それに従って制作をすすめるサブコーダーと、事前に役割を決めることを推奨します。
開発環境
開発環境は様々ありますが、所属している会社で推奨している構築ルールを掲載します。ルール多くなればなるだけ制作工数がかかり、難易度が高くなるため、当ガイドでは最低限守られるべきルールのみを指定しています。
ツール選定について
npm scriptやgulp、Codekitなど、開発ツールは多々ありますが、当ガイドラインでは開発ツール強制は行いません。開発チームや各端末に合わせた最適な環境を構築してください。
ツール例
ディレクトリ設定
ディレクトリの設定は以下を推奨します。gitで管理していく想定の構成です。git直下には基本何も配置せずに、htdocs配下にサイトデータ一式を入れてください。
.gitignore
README.md
htdocs
├─ assets
└─ css
├─ fonts // Webフォントがある場合の格納先
├─ images
└─ commons //共通で利用する画像
└─ page //各ページごとに画像格納
└─ js
└─ page //各ページディレクトリ
HTML
基本ルール
- インラインでCSS、javascriptは書かない
- 1P以上のWebサイトの場合、リンク・画像はサイトルート相対パスに設定
例: /hoge/img.png - .htmlをphpとして動かすなどの、拡張子偽装は行わない
- インデントはスペース2つで設定する
- 納品前にコードインデントを行い、可読性を上げる
画像
- 画像の書き出しは基本的にjpgで。透過処理が必要な画像のみPNGで書き出し
- ロゴやアイコンなど、ビットマップ処理が無い軽量な画像はsvgで書き出す
- 画像は書き出した後にTinyPNGやimgminなどで圧縮を行う
コンテンツタグ・SEO
- <h1>タグはページにひとつだけ設ける
- <h1>,<h2>などのSEOとして重要なタグは、メニューやヘッダーなど、各ページ共通で使うパーツやコンポーネントでは利用しない
計測タグ・ソーシャルタグ
- 正しい挿入位置に指定タグを設置する
- 同じタグを複数回読み込まない
- ソーシャルタグの読み込みは表示を遅くするため、設置不要な場合は削除する
テンプレート
弊社でよく使う、ベースのテンプレートファイルです。body配下の具体的指定は行いません。また、各タグの詳細説明は省略します。利用ケースに合わせて削除・追記してください。
HTMLテンプレート
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="format-detection" content="telephone=no">
<meta name="description" content="">
<meta name="twitter:card" content="">
<meta name="twitter:title" content="">
<meta name="twitter:description" content="">
<meta name="twitter:site" content="">
<meta name="twitter:image" content="">
<meta name="theme-color" content="">
<meta name="apple-mobile-web-app-title" content="">
<meta property="og:locale" content="">
<meta property="og:type" content="">
<meta property="og:url" content="">
<meta property="og:title" content="">
<meta property="og:description" content="">
<meta property="og:site_name" content="">
<meta property="og:image" content="">
<link rel="canonical" href="">
<link rel="apple-touch-icon" sizes="57x57" href="">
<link rel="apple-touch-icon" sizes="60x60" href="">
<link rel="stylesheet" href="">
<title></title>
</head>
<body>
</body>
</html>
PHPテンプレート
PHPを使う場合は、inculdeやrequire_onceなどを使って各コンポーネントやパーツを読み込んで使うケースが多いです。主に中規模以上のページ、WordPressを導入するWebサイト等で利用します。
<?php
const PAGE_ID = 'home';
const PAGE_DESC = 'ディスクリプションが入ります';
const PAGE_TITLE = 'タイトルが入ります';
?>
<?php include('../assets/components/head.php'); ?>
<!-- ここにページ內容を書く -->
<?php include('../assets/components/footer.php'); ?>
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="format-detection" content="telephone=no">
<meta name="description" content="<?php echo PAGE_DESC; ?>">
<meta name="twitter:card" content="">
<meta name="twitter:title" content="<?php echo PAGE_TITLE; ?>">
<meta name="twitter:description" content="<?php echo PAGE_DESC; ?>">
<meta name="twitter:site" content="">
<meta name="twitter:image" content="">
<meta name="theme-color" content="">
<meta name="apple-mobile-web-app-title" content="">
<meta property="og:locale" content="">
<meta property="og:type" content="">
<meta property="og:url" content="<?php echo (empty($_SERVER['HTTPS']) ? 'http://' : 'https://') . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']; ?>">
<meta property="og:title" content="<?php echo PAGE_TITLE; ?>">
<meta property="og:description" content="<?php echo PAGE_DESC; ?>">
<meta property="og:site_name" content="">
<meta property="og:image" content="">
<link rel="canonical" href="<?php echo (empty($_SERVER['HTTPS']) ? 'http://' : 'https://') . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']; ?>">
<link rel="apple-touch-icon" sizes="57x57" href="">
<link rel="apple-touch-icon" sizes="60x60" href="">
<link rel="stylesheet" href="">
<title><?php echo PAGE_TITLE; ?></title>
</head>
<body>
<!-- ここでscriptを読み込む -->
</body>
</html>
参考
CSS
基本ルール
- リンク・画像はサイトルート相対パス、相対パスのいずれかで設定
- 納品前にコードインデントを行い、可読性を上げる
- インデントはスペース2つで設定
下準備
CSSの作成を行う前に、必ずCSSの初期化を行ってください。当ガイドではReset CSS系統での初期化を推奨しています。
reset.cssの指定に加えて、以下の定義を必須とします。
html, bodyの初期化
html {
width: 100%;
height: auto;
font-size: 62.5%;
}
body {
width: 100%;
}
box-sizingの有効化
* {
box-sizing: border-box;
}
img初期化
img {
max-width: 100%;
vertical-align: top;
}
font初期化
font-feature-settings: "pwid" 1;
-webkit-font-smoothing: subpixel-antialiased;
-moz-osx-font-smoothing: unset;
-webkit-text-size-adjust: 100%;
書体はサイト全体で利用している書体に合わせ、bodyに指定してください（macOS Catalina用にアップデート）
font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Helvetica Neue', 'Hiragino Sans', 'Hiragino Kaku Gothic ProN', 'ヒラギノ角ゴ ProN W3', Meiryo, 'メイリオ', 'ＭＳ Ｐゴシック', 'MS PGothic', Osaka, arial, sans-serif;
ゴシックでbold指定をする場合、font-weightをbold指定するとHiragino Sans W7のweightが指定されてしまい、Hiragino Kaku Gothic ProNでbold指定した場合と見た目が変わってしまいます。
太文字設定する場合、font-weight: boldで指定するのではなく、font-weight: 600を指定してください。
font-family: "Yu Mincho", YuMincho, "Hiragino Mincho ProN", Georgia, "游明朝", "HGS明朝E", serif;
明朝体についてはHiragino Mincho ProNが引き続きバンドルされるのでウエイト指定はそのままで問題ありません。macOS Catalinaでバンドルされているフォントの確認はこちらからご確認ください。
ハック処理
IE11でsvgが崩れる対策
@media screen and (-ms-high-contrast: active),
(-ms-high-contrast: none) {
img[src$=".svg"] {
width: 100%;
}
}
Webフォント
- 日本語Webフォントを使う場合、原則見出しのみとする
- 日本語Webフォントをサイト全体に使う場合、読み込むデータ量によってFOIT/FOUT問題が発生するため、
font-displayによる対応、またはJavascript（Font Face Observerを推奨）による遅延ロードなどを行い、レスポンスの改善を行う - 英語Webフォントは軽量なので、大量に読み込む場合を除き考慮しない
参考
プリプロセッサ
本ガイドでは**SASSの利用、及びSCSS記法を推奨します。**ページが複数あり、後述する設計方法を利用する場合は必須とします。
Sass: Syntactically Awesome Style Sheets
CSS設計
CSS設計手法は多々ありますが、制作するWebサイトの傾向によって向き不向きがあります。ここでは経験値に基づき、ページ数を基準とした望ましい設計方法を記載します。当ガイドではおおよそのケースで対応できるFLOCSSの利用を推奨しています。
| 基準 | 推奨設計 | 推奨理由 |
|---|---|---|
| 1P | OOCSS 等 | 基本どんな設計でもよい。ただし、定期的に更新を行う必要があるページの場合は、更新部分の構造を検討する必要がある |
| 小規模（10P前後） | FLOCSS、BEM等 | 影響範囲がそこそこの場合、ページ単位で管理できる設計方法を推奨 |
| 中規模以上 | FLOCSS | ページ単位で設計できることに加えて、使いまわすモジュールコンポーネントの定義ができる設計方法が必須 |
| 管理画面・Webアプリ | SMACSS、 FLOCSS、 SUIT CSS 等 | ひとつのコンポーネント中で、複数の状態管理が必要。状態管理に向いた設計手法を推奨 |
各公式ページ
CSSフレームワークの利用について
本コーディングガイドでは、BootstrapやFoundationなどの大規模CSSフレームワークの利用を原則禁止します。ただし、component単位等の小規模なフレームワークの利用は許容します。
理由
Bootstrapなどの大規模フレームワークを導入して、高速にコーディングができるケースはもちろんあります。しかし、以下の条件に当てはまる場合、後の開発フローになるにつれ、崩壊の兆しがでてきます。
- CSSフレームワークのコンポーネント・レイアウトシステムを考慮していないデザイン
- メインコーダーがCSSフレームワークを初めて使う
- 利用するCSSフレームワークの理解が、チームで一定でない
利用しなくてはならない場合、または利用を前提としたコーディングを行う場合、利用CSSフレームワークのレイアウトシステム・及びベースとなるコンポーネントに沿ってデザイン、設計を行う、チーム内で学習・検証した上で導入することを大前提としてください。
実装（Javascript, PHP等）
プログラムの実装は、実装担当者のレベルによって品質が大きく変わってきます。そのため、あくまで必須ルールのみを列挙します。ここでは最も多く使うPHP、Javascriptについて説明しています。
ルール
- 所謂普通のWebサイトの場合、状態管理が複雑になることがほとんどないため、情報量が多く実績もある、jQueryの利用を許容する
- CDNでリソースファイルを読み込む場合、プロジェクトの性質と設計方針を確認した上で利用する
- Javascript記述は、可読性とメンテナンス性を考慮して極力外部ファイル化する
- PHPで共通コードが多数使われる場合は、メンテナンス性と再利用性を考えて外部ファイル化する
- コピペで同じリソースファイルを読み込ませない
例：jQueryをhead、body別々に2回読んでいる、など - jQueryの
readyなど、1つだけで動作するものは複数に分けないでまとめて記述する - 1ページ以上で共通パーツがある場合、
includeする仕組みを構築する - コードインデントを行い、可読性を上げる
- 開発ツールを使ってbuild後のコード圧縮を行う（推奨）
SEOフレンドリーな実装
アプリと違い、企業WebサイトはSEOを重視しているケースがほとんどなため、主要コンテンツの描画をクライアントサイド側で行って動的に表示することは原則NGです。
動的に出力する必要がある場合は、PHPを使う、またはNode.js環境をサーバに構築してレンダリングするなど、検索エンジンにインデックスする仕組みの構築を行ってください。
コーディング後
.htaccessの設定
.htaccessの詳細な設定方法はサーバ仕様によって大きく変わるため、本ガイドでは詳細な記載を行いませんが、動作をコントロールする重要な事項です。よくあるケースとしては以下のような設定が求められます。
- ベーシック認証
- URL正規化
- 301または302リダイレクト
- 404リダイレクト
参考
コードチェック
作業担当者がコードチェックを行う場合、客観的にチェックできないケースが多いです。基本的なチェックはコーダーだけでなく、発注側やチェッカーと共同で行うことを推奨します。その上でコードのチェックを機械的に行うツールの導入し、効率的にチェックをしてください。