design-whitespace

name	design-whitespace
description	Web/UIの余白を計測し、macro/meso/microの階層、vertical rhythm、情報密度、レスポンシブ挙動として設計・実装・検証する。spacing、margin、padding、gap、section間隔、詰まり、間延び、密度、呼吸感、縦リズム、モバイル余白、Tailwindの余白調整、またはmockup-to-codeで計測済みカンプの余白を実装するときに使う。

Design Whitespace

余白を空きではなく、情報のまとまり、優先順位、読み進行、操作性を制御するレイアウト構造として扱う。印象だけで調整せず、基準値、実測値、変更値、検証結果を残す。

実行契約

入力を確定する

作業前に次を確認する。存在しない項目は unknown と記録し、忠実再現に必要な値が欠ける場合だけ停止する。

• 対象画面、変更可能なファイル、既存デザインシステム
• 基準viewportと検証viewport
• 実コンテンツまたは長さが同等の代表コンテンツ
• 参照カンプ、現状スクリーンショット、または改善目的
• 既存のspacing token、breakpoint、container、type scale
• ユーザーが指定した密度、ブランド印象、アクセシビリティ要件

値の優先順位を固定する。

1. 正規化済み参照カンプから得た計測値
2. ユーザーが明示した値と受け入れ条件
3. リポジトリのdesign tokenと既存コンポーネント規則
4. 同種要素から得たページ内の反復値
5. このスキルの比率・スケールを使った仮説値

上位の値を下位の慣例で上書きしない。DOMRectは実装結果の計測に使い、参照カンプの根拠にすり替えない。

出力を残す

最終的に次を提示する。小規模な調整では回答内の表でよい。作業用レポート規約がある場合はその場所へ保存する。

• spacing scale: token名、px/rem値、用途
• whitespace plan: 領域、階層、基準値、変更前、変更後、根拠
• responsive rules: viewportごとの維持・縮小・再配置・解除
• exceptions: スケール外の値、理由、適用範囲
• validation: viewport、実測値、画像またはDOMRectの証拠、判定
• status: passed / needs_work / blocked

ワークフロー

1. 現状を計測する

コード変更前に基準状態を保存する。

1. 各viewportでページ全体と対象領域のスクリーンショットを撮る。
2. セクション境界、container左右端、主要要素のbboxを測る。
3. computed styleから margin、padding、gap、line-height、width、min-height を取得する。
4. 繰り返す同種要素の値を集計し、中央値と外れ値を記録する。
5. 最初に壊れている階層を macro、meso、micro のいずれかに分類する。

ブラウザ計測では重要要素へ安定した data-el を付け、同じselectorを変更前後で使う。DevToolsまたはブラウザ自動化のevaluateで次を実行し、結果をJSONとして保存する。

Object.fromEntries(
  [...document.querySelectorAll('[data-el]')].map((el) => {
    const r = el.getBoundingClientRect();
    const s = getComputedStyle(el);
    return [el.dataset.el, {
      x: r.x, y: r.y, width: r.width, height: r.height,
      margin: [s.marginTop, s.marginRight, s.marginBottom, s.marginLeft],
      padding: [s.paddingTop, s.paddingRight, s.paddingBottom, s.paddingLeft],
      gap: s.gap, lineHeight: s.lineHeight, position: s.position
    }];
  })
)

隣接bboxの縦間隔は next.top - previous.bottom、左右gutterは container.left と viewportWidth - container.right で計算する。スクロール位置を固定し、font読込完了後に計測する。小数値は保持し、表示時だけ丸める。

最低限、次の計測表を作る。

領域	viewport	階層	計測対象	基準値	現状値	差分	根拠
hero→next	1440	macro	section boundary gap	96	128	+32	comp bbox

単一viewportのpxだけを見て結論を出さない。基準viewport以外では、固定値ではなくレイアウト関係が保たれるかを確認する。

2. Macroを整える

ページ全体の呼吸と大きな区切りを先に直す。

• viewport edge→container、header→hero、section→section、page endを測る。
• sectionの上下padding、container幅、背景切替、full-bleed領域を定義する。
• 連続するsectionの空白量を並べ、意図のない均一化と極端な空白runを検出する。
• 上下sectionのpaddingが重複して境界だけ過大になっていないか確認する。
• 重要sectionを単純に広くせず、前後との対比と読み進行で強調する。

Macroが不安定な間は、カード内paddingなどのmicro調整へ進まない。

3. Mesoを整える

意味のまとまりとコンポーネント間の関係を直す。

• eyebrow→heading→lead→CTAを一つのclusterとして測る。
• gridの列間・行間、card間、media→copy、list item間を測る。
• 同種clusterは同じ規則へ寄せ、内容差がある場合だけ例外化する。
• 見出し後より次の見出し前を大きくし、所属関係を視覚化する。
• gap、親のstack、gridで関係を表現し、子への散発的なmargin追加を避ける。

4. Microを整える

要素内部と隣接要素の精度を上げる。

• button、input、chip、label、icon+text、caption、inline groupの内部paddingとgapを測る。
• textの実glyphだけでなくline boxを確認し、見かけの余白差を補正する。
• iconのviewBox内余白をCSS gapの不足と誤認しない。
• 1〜2pxの補正は、光学補正や境界線整合など測定可能な理由がある場合だけ局所tokenとして残す。
• 操作要素はプロジェクトのtarget-size要件を満たす。余白を詰めるために操作面積を削らない。

5. Vertical rhythmを検証する

縦方向を上から順に追い、隣接関係を実測する。

1. blockの上端・下端とbaseline/line boxを記録する。
2. heading→body、body→support、cluster→cluster、section→section の反復値を比較する。
3. CSS margin collapse、空要素、絶対配置、画像のbaseline隙間による見かけとcomputed valueの差を確認する。
4. line-heightをspacingの代用品にしない。テキスト内部のリズムとblock間隔を分離する。
5. 例外を除き、同一の意味関係を同一tokenへ収束させる。

リズムは「すべて等間隔」ではない。小・中・大の反復と、section転換時の意図的な休止を作る。

6. Densityを制御する

密度を雰囲気語だけで決めず、次の代理指標を変更前後で比較する。

• viewport内に見える主要情報単位数
• section高に対する主要content bbox高の比率
• 最大連続空白runとsection高に対する比率
• card/listの行数、行間、item間隔
• CTA到達までの縦距離
• 折返し行数とテキストblock高

密度を上げる場合も、まず冗長なmacro空白と重複paddingを削り、可読性や操作性を支えるmicro余白は最後まで守る。密度を下げる場合は全値を一律拡大せず、重要clusterの前後に差をつける。

7. Mobileを別レイアウトとして確認する

desktop値の一律縮小で済ませない。

• 実際の狭幅で折返し後のblock高、CTA位置、sticky/fixed UI、safe-area、keyboard表示時を確認する。
• container gutterは最小値を守りつつ、長い見出しや横並びUIの実測から決める。
• 多列をstackへ変更した後、desktopのcolumn-gapを縦gapへそのまま流用しない。
• 情報の所属を示すmicro/meso差を保ち、全要素が同じ縦間隔になることを避ける。
• 390pxだけでなく、対象プロジェクトの最小幅、中間幅、desktop幅を検証する。
• 参照mobileカンプがない忠実再現では、desktopの関係性を保ったresponsive仮説として明記し、推測値を参照実測値と混同しない。

8. 実装する

• 既存tokenを再利用し、不足する意味だけ追加する。
• CSS custom propertiesまたは設定済みframework tokenに値を集約する。
• sectionはpadding、内部配列はgap、要素内部はpaddingを基本とする。
• space-y-* は単純な同種stackに限定し、複雑な関係は明示したgrid/flex gapで表す。
• 任意値は計測された参照値、光学補正、または既存制約に必要な場合だけ使う。
• 負のmarginは意図したoverlapに限定し、通常の余白修復には使わない。
• レイアウトを合わせるために内容要素をabsolute配置しない。

スケールを新規に作る場合は4px基準から始め、役割で命名する。例: micro 4/8/12、meso 16/24/32、macro 40/56/72/96。これは初期仮説であり、参照カンプや既存tokenより優先しない。詳細なTailwind対応が必要な場合だけ references/spacing-system.md を読む。

9. 再計測して収束させる

1. 同じviewport、同じcontent、同じfont状態で再レンダーする。
2. 最初に失敗した要素をdocument orderで一つ直す。
3. Macro→meso→microの順を崩さず、変更ごとに再計測する。
4. 基準値と実測値の差、ratio、折返し、overflow、layout shiftを確認する。
5. screenshot差分を目視し、数値が合っても所属・読み順・密度が崩れていればneeds_workにする。
6. 全viewportを再確認し、局所修正が別幅を壊していないことを確認する。

許容差はユーザー指定、manifest、または既存QA規約を使う。許容差がない場合は差分を報告し、根拠なく合否閾値を発明しない。

mockup-to-code接続契約

mockup-to-code と併用する場合は、同スキルのmanifest、LAYOUT LAW、FV FIRST、box-diff、computed completion verdictを上位契約として扱う。このスキルは余白計画と余白差分の修復を担当し、独自の完了判定で上書きしない。

接続phase	開始条件	必須input	output	停止条件
WS-A 計画	mockup Phase 0〜3完了後、CSS実装前	正規化frame、source viewport、source由来bbox/section bands/container edges、manifest priority	macro/meso/micro分類、spacing token案、section rhythm表、responsive仮説	frame未正規化、source viewport不明、重要bboxが未計測、DOMRectしか根拠がない
WS-B 修復	Phase 6〜7の初回render後	manifest、box report、comp/build crop、DOMRects、computed styles	document orderのfirst failing spacing、変更値、再計測結果	FV-critical余白が未収束、根拠のないtolerance変更、下位階層の変更が上位差分を隠す
WS-C responsive	Phase 9	mobile/中間/desktop render、width sweep、mobile compまたはresponsive仮説	viewport別の維持/縮小/stack/解除規則、overflowと空白runの判定	重要幅のrender欠落、mobileでcontent欠落・重なり・横overflowがある

計測値を最優先する。カンプ上のsection境界、bbox間距離、container edge、空白runをsource座標で計算し、実装後のDOMRectとの差を比較する。見た目の推測でmanifest値を埋めず、実装値からsource値を逆算しない。

FVのmacro/meso差分が停止条件に触れた場合は、below-FVの余白実装へ進まない。余白だけが合っても、mockup-to-code のasset、typography、layout-law、artifact、completion gateが未達なら完了と報告しない。

完了条件

次をすべて満たした場合だけpassedとする。

• Macro、meso、microの各層に基準と実測がある。
• Vertical rhythmの反復値と例外理由を説明できる。
• Density指標が変更前後で記録され、目的方向へ変化している。
• 最小幅、中間幅、desktop幅でoverflow、重なり、意図しない巨大空白がない。
• 変更値がtoken、計測値、または明記した光学補正へ結び付いている。
• スクリーンショットとDOM/computed styleの両方で検証している。
• mockup接続時は上位のartifact/check/gateが成功している。

必要な参照計測やviewportが得られなければblocked、実装は動くが差分・証拠・幅検証が残ればneeds_workとする。検証結果のない「整えた」「自然になった」は完了報告にしない。