PR TIMES社内のHTMLクライテリアを作成しました

2025年2月5日

こんにちは。PR TIMESでフロントエンドエンジニアをしている夛田(@unachang113)です。

今回はPR TIMES社内でHTMLクライテリアを作成したのでその話をしようと思います。

つくろうと思ったきっかけ

PR TIMES社内ではHTMLの品質に対するエンジニア間の共通の指標がなかったため、何を満たせば品質を担保していると言えるのかの指標やルールがありませんでした。

指標がないとlintを導入した際に何を入れると品質が向上できるのかがわからなかったり、HTMLの仕様理解が個々人ばらつきが生じ、プロダクトコードで品質を担保するのが難しくなります。

そこでPR TIMESの開発部のフロントエンドチームにおけるHTMLの品質を明文化するためにクライテリアを作成することにしました。

日本CTO協会が作成しているWebフロントエンド版DX Criteriaをベースに作成を行いました。

まず、クライテリアの作成に入る前に、PR TIMES社内におけるHTMLの品質を担保するためになにが必要なのかのドキュメントを作成してメンバー内での合意を取りました。

基準を作成する際、ISO/IEC 25000に定義されているソフトウェアにおける品質特性と照らし合わせて8つの指標でHTMLの品質について考えました。

機能適合性（機能がユーザーのニーズを満たせているか）
- ユーザーが操作を行う際に迷わないように適切なHTML要素を使用していること ex. ボタンをdiv要素で実装しない
性能効率性（リソースに対してどれだけの性能を発揮できるか）
- パフォーマンスを意識したHTMLが書けていること ex. 不要な要素がHTMLファイル上に含まれていないか、CLS（Cumulative Layout Shift）が低下するような記述になっていないか
互換性
- さまざまな機種・スマートフォンからアクセスした際に同じの機能が提供できること
使用性
- ユーザーが操作を行う際に迷わないマークアップになっていること
信頼性
- 動作を保証しているブラウザで表示崩れの障害が起こらないこと
セキュリティ
- HTML要素を適切に設定しなかったことによるセキュリティインシデントがないこと
保守性
- 表示の不具合が生じた場合に原因箇所が容易に特定できること
- コンポーネントの分け方の粒度が統一されていること
- 個々人の書くHTMLのクオリティにばらつきが無いこと
移植性
- 動作を保証しているブラウザで表示崩れが起こらないこと
- 他のプロジェクトをまたいで共通のHTMLコンポーネントが利用できること

また、基準を作成する際に以下のサイトを参考にしています。

1で作成したHTMLの品質を担保するための基準を元に、フロントエンドのアドバイザーのsensuiさんと相談しつつ、以下の2つの大カテゴリとそれに紐づく小カテゴリをそれぞれ設定しました。

Webフロントエンド版DX Criteriaを参考に、各カテゴリ毎以下の4つの観点を満たすための判断基準を作成しました。

例えば、上で上げた小カテゴリの中のUIコンポーネントを各判断基準に落とし込んだものが以下になります

メトリクスの計測
- markuplint等のリンターで広く共通化を意図しているUIコンポーネントのマークアップが問題ないかの点検を日常的（日ごと〜週ごと）に実施している。
  headingsMapなどのアウトラインを確認するツールで文章構造がおかしくないかを確認している
学習と改善
- UIのマークアップに関する議論をチーム内で行い逐次共有している。
プラクティス
- 開発プロセスの中でHTMLの利用やアウトラインが妥当かをレビューの際に判断している。
  headingMapなどのアウトラインを確認できるツールで文章構造がおかしくないかを実装時に確認しながら進めている
アンチパターン
- 同じ様な用途のUIをいくつも作成してしまう。（共通化されていない）
  HTMLの意味が正しくない用途で使われているコンポーネントが汎用的に利用されている