Docs: Make Titles Flush Again 🚽

.wa-prose が h1 要素に付与する margin-block-start により、ページ上部のパンくずリスト直後に余計な余白が生まれていました。本 PR はその余白を取り除き、タイトルを左詰め(Flush) に戻すための CSS 修正を行います。変更はドキュメントのビジュアル一貫性を回復し、閲覧体験を向上させます。

背景

.wa-prose は本文フローを整えるために * + h1 { margin-block-start: var(--wa-space-l); } を適用しますが、ドキュメントページではパンくずリスト (.page-breadcrumbs) の直後に h1 が続くケースが多く、意図しない上部余白が出現しました。この余白はページタイトルが他要素と離れすぎて見える原因となり、デザインガイドラインに背いていました。そこで余白を除去し、ページタイトルを「Flush」状態に復元する必要がありました。

技術的な変更

変更前のスタイル (削除対象)

/* The breadcrumb is navigation, not prose flow — drop wa-prose's
   previous-sibling top margin on the page title that follows it. */
.page-breadcrumbs + h1 {
  margin-block-start: 0;
}

上記ルールは .page-breadcrumbs の直後に来る h1 の上余白を 0 にリセットしていましたが、スコープが限定的すぎてメンテナンス上の一貫性が欠けていました。そこでこのルールを削除し、より汎用的なタイトルセレクタへ置き換えました。

変更後のスタイル (追加)

h1.title {
  /* Siblings above own their block-end spacing — skip wa-prose's `* + h1` top margin. */
  margin-block-start: 0;

  wa-badge {
    vertical-align: middle;
    font-size: 1.5rem;
  }
}

h1.title に対し直接 margin-block-start: 0; を設定することで、.wa-prose が付与する上余白を上書きします。コメントで意図を明示し、同様の問題が再発した際の指針をコード上に残しています。結果として、ページタイトルは常にフラッシュ表示され、余計な空白が除去されます。

設計判断

余白除去のアプローチとして 汎用的なセレクタ (h1.title) を用いた点が重要です。個別の隣接セレクタ (.page-breadcrumbs + h1) を削除し、タイトル全般に対して一貫したスタイルを適用することで、将来的なレイアウト変更や新しい前置要素が追加された場合でも同様にフラッシュ表示が保たれます。また、コメントでデザイン意図を残すことで、他の開発者が意図を誤解せずに拡張できる設計となっています。

まとめ

今回の CSS 修正は、.wa-prose が付与するデフォルトの上余白を h1.title で上書きし、タイトルを左詰めに戻すシンプルかつスコープの広い解決策です。余計な余白が除去されたことで、ドキュメントページのビジュアル一貫性が回復し、ユーザ体験が向上します。