コンポーネント化している部分のhタグを変更できるようにしたい／PHP、Pugの場合

アクセシビリティの観点から、よく「適切な見出しの階層構造を保とう」と言われると思います。

つまり、「見出しのタグ（h1〜h6）を適切に順番に書き、見出しと内容をしっかり分かるようにする事でページ全体の構造を理解しやすくするようにしましょう」という事になります。

階層構造がしっかり保たれていると

• 「このページは大まかには●●について書かれている。その中で◎◎と⚪︎⚪︎という2つのトピックがあり、さらに詳しい説明がある」 という風に、ページ全体の構成が一目瞭然になります。
  誰にとっても読みやすいページになりますので、アクセシビリティに繋がります。

• Google などの検索エンジンも、ページの見出しを読むことで「このページは何について書いているのか」を判断します。
  なので、階層構造が正しいほど検索エンジンはページの内容を正確に理解でき、SEOにも繋がっていきます。

• 「スクリーンリーダー」は見出しを読み上げます。見出しが正しい順序（h1 → h2 → h3…）で並んでいれば、ページの全体像を素早く理解してもらえるようになります。

...ですが、正直なところ、コーディングをやっている人間のほとんどはこれを無意識に気をつけているのではないかと感じております。
しかし、これが突如狂ってくる時があります。
例えば...。

思わぬ事態の例

例1. 「<h2>部分は削除になりました」となった場合

（Before→After）

<h2>が無くなったので、<h3>だったものは<h2>へジョブチェンジします。
静的なhtmlファイルであれば、少し泣きながら書き換えれば一応なんとかその場はおさまります。

※「削除しない方がいいと思います。このタイトルを消してしまうと構造が破綻してしまいますのでSEO、アクセシビリティ的にもおすすめしません」と伝えることももちろん大切です。
SEOやアクセシビリティに関しては、お客さまとも協力が必要です...難しい事です。

しかし「動的な部分がある」、「コンポーネント化している部分」であった場合どうでしょうか。

例2. 「<h2>部分は削除になりました」となった場合２

（Before→After）

例2-2.  下層ページを追加することになり、しかも階層構造が違っていた場合

（TOP ＋ 下層ページ）

コンポーネント化しておいたカード型レイアウトのタイトル部分が、hタグに振り回される状態になってしまいました。
しまった…悲しい…という気持ちしか湧きません。
「仕方がない、すべて <h3> でやってしまおう！」と強行突破するのはNGです。

こんな時、hタグが変わったりしても大丈夫なように実装してみたいと思います。

やってみる - PHP編

WordPressで実装していると仮定してやってみたいと思います。
PHPでコンポーネント（テンプレート）を呼び出す際、引数を経由してhタグを渡すことで、hタグを変更できるようにしていきます。

説明のため、リンク先を出力するコード <?php echo esc_url( $item['permalink'] ); ?> などなどは割愛しております。予めご了承ください。

【コンポーネント側】

呼び出し側から渡されたhタグを受け取り、もし<span>や<h1>などの想定外のタグが渡された場合の対策も念のため入れておきます。

▼PHP（例：template-parts/news-card.php）

<?php
  // 呼び出し側から渡されたデータを取得
  $item = $args['item'];

  // 指定がなければデフォルトは 'h3' にする
  $heading_tag = $args['heading_tag'] ?? 'h3'; 

  // 念のため許可するタグを限定しておく
  $allowed_heading_tags = ['h2', 'h3', 'h4']; 

  // 許可されていないタグが指定されていたら 'h3' に上書き
  if (!in_array($heading_tag, $allowed_heading_tags, true)) {
    $heading_tag = 'h3';
  }
?>

<a class="c-newscard" href="#">
  <div class="c-newscard-photo">
    〜略〜
  </div>
  <div class="c-newscard-header">
    <time class="c-newscard-header__date" datetime="yyyy-mm-dd">yyyy.mm.dd</time>

    <<?php echo esc_html( $heading_tag ); ?> class="c-newscard-header__title">
      ダミータイトル
    </<?php echo esc_html( $heading_tag ); ?>>

  </div>
  <div class="c-newscard-body">
    〜略〜
  </div>
  <div class="c-newscard-footer">
    〜略〜
  </div>
</a>

【呼び出し側】

呼び出し側では、配列（$args）の中に 'heading_tag' => 'h2' のように、その場所の文書構造として適切なhタグを指定してコンポーネント（テンプレート）を読み込みます。

▼PHP（例：archive-demo.php）

 <?php
  // 記事のデータを取得（独自の関数などを想定している場合）
  $item = demo_get_news_item(get_the_ID());

  // コンポーネントに渡す引数を配列で定義
  $args = [
    'item'        => $item,
    'heading_tag' => 'h2', // 配置場所に合わせてhタグを書き換える
  ];

  // コンポーネント（テンプレート）を読み込む
  get_template_part( 'template-parts/news-card', null, $args );
?>

▼出力結果

<a class="c-newscard" href="#">
  <div class="c-newscard-photo">
    〜略〜
  </div>
  <div class="c-newscard-header">
    <time class="c-newscard-header__date" datetime="yyyy-mm-dd">yyyy.mm.dd</time>
    <h2 class="c-newscard-header__title">
      ダミータイトル
    </h2>
  </div>
  <div class="c-newscard-body">
    〜略〜
  </div>
  <div class="c-newscard-footer">
    〜略〜
  </div>
</a>

【ポイント】

ちょっとした事ですが、hタグに直接CSSでスタイルを作らず、 .c-newscard-header__title にスタイルをあてることでhタグだけ書き換えれば大丈夫なようになっています。

<h2 class="h2"> というようなクラス名も避けましょう。
もしh3に変わった場合、<h3 class="h2"> となってしまい大変苦しい事になります。
未来の自分のためにもしっかり設計しておきたいところです。

やってみる - Pug編

案件によっては活躍する、HTMLを効率的に書くためのテンプレートエンジン「Pug」。
こちらでも同じようなことができます。
Pugでは、#{変数名} を使うことで、タグ自体を変数にすることができます。

こちらも説明のため、もろもろの変数を割愛しております。本来はタイトルや画像なども変数に含めた方が大変便利です！予めご了承ください。

【コンポーネント側】

オブジェクト形式で引数（args）を受け取るように定義します。
引数を受け取れる mixin を使用してやってみます。

▼Pug（例：_news_card.pug）

mixin newsCard(args)
  //- 指定がなければデフォルトは 'h3' にする
  - var news_card_title_tag = args.news_card_title_tag || 'h3'
  
  a.c-newscard(href="#")
    .c-newscard-photo 〜略〜
    .c-newscard-header
      time.c-newscard-header__date(datetime="yyyy-mm-dd") yyyy.mm.dd
 
      //- 配置場所に合わせてhタグを書き換える
      #{news_card_title_tag}.c-newscard-header__title ダミータイトル
      
    .c-newscard-body 〜略〜
    .c-newscard-footer 〜略〜

【呼び出し側】

include でmixinファイルを読み込み、関数を呼び出すように引数を渡します。

▼Pug（例：index.pug）

include _news_card.pug

//- h2に指定の場合
+newsCard({
  news_card_title_tag: 'h4'
})

▼出力結果

<a class="c-newscard" href="#">
  <div class="c-newscard-photo">〜略〜</div>
  <div class="c-newscard-header">
    <time class="c-newscard-header__date" datetime="yyyy-mm-dd">yyyy.mm.dd</time>
    <h4 class="c-newscard-header__title">ダミータイトル</h4>
  </div>
  <div class="c-newscard-body">〜略〜</div>
  <div class="c-newscard-footer">〜略〜</div>
</a>

まとめ

「アクセシビリティを保ちながらパーツを使い回したい」時になんとかするお話でした。

PHP（WordPressなど）やPugを使うと「hタグは呼び出し側から設定できる」 と覚えておくと、SEOにもスクリーンリーダーにも優しいサイトが作れます。

しかしパーツの使い回しをしすぎるのもあまり良くありませんので、使い回しても良いところかどうかをしっかり見極めながら、丁寧に実装していきたいです。
デザイナーさんやお客さまとも（相談ができるようであれば）しっかり相談しましょう。

アクセシビリティは紐解いていくと正直難しいですが、hタグの順番をしっかり守る事を意識し続けるだけでも、勉強につながっていくのではないかと個人的に思います。
最後まで読んでいただき、ありがとうございました。