📱 ポータル制約仕様書

対象: ひつまぶしへ掲載するゲーム（HTML5 / JavaScript / iframe）の開発者・クリエイター向け。 概要: ゲームは PC・スマートフォン・タブレット・OBS など多様な環境の <iframe> 内で動きます。 ここに書かれているのは推奨ではなく制約で、外すと特定の環境で操作できない・表示が崩れる といった形で壊れます。守れているかの確認手段は 検証 にあります。

---

1. タッチターゲット最小サイズ（44 × 44 px）

要件

すべての操作可能なUI要素（ボタン・リンク・トグル・カード等）は、
タッチターゲットの最小サイズを 44 × 44 px 以上で実装してください。
これは Apple Human Interface Guidelines および
WCAG 2.5.5 Target Size (AAA) の基準に準拠しています。

実装例

/* ❌ 不適切: タッチターゲットが小さすぎる */
.small-btn {
  padding: 2px 6px;
  font-size: 0.7rem;
}

/* ✅ 適切: 最小 44×44px を確保 */
.action-btn {
  min-width: 44px;
  min-height: 44px;
  padding: 10px 16px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
}

注意事項

• アイコンのみのボタン（閉じる ×、次へ ▶ 等）は視覚サイズが小さくても、
  padding や ::before / ::after 疑似要素でタッチ領域を 44 px 以上に拡張すること。
• モバイル幅（< 640px）では特に注意。PC では問題なく見えても、スマートフォン実機でタップしにくい場合がある。

例外：多セルのグリッド盤面

N×Nのグリッド盤面では、この規定を全セルに適用すると盤面が画面に収まりません（9×9で幅396px以上、15×15で660px超が必要になり、多くのスマートフォンで破綻します）。

そのため盤面のセルに限り、AAA（44px）ではなく AA（24px）を満たすことを許容します。独自に基準を緩めているのではなく、適用する標準を1段下げるという選択です。

	基準	間隔による例外
WCAG 2.5.5 Target Size (Enhanced)	AAA / 44 × 44 px	無い
WCAG 2.5.8 Target Size (Minimum)	AA / 24 × 24 px	ある（Spacing）

例外が適用される条件（すべて満たす場合のみ）:

1. 対象が「隙間なく隣接して並ぶ同種のセル」であること（単独で存在するボタン・メニュー・ミュート等は対象外で、44px規定を維持する）
2. 誤タップの結果が隣のセルへの着手にとどまり、退出・課金・リマッチ等の不可逆な操作を含まないこと
3. セル間に視認できる境界（罫線・gap）があり、境界がどこかタップ前に判別できること

判定はセル1辺ではなく「ピッチ」で行います

WCAG 2.5.8 の Spacing 例外は、各ターゲットの中心に直径24pxの円を置いてそれが隣と重ならないことを求めています。隙間なく並ぶグリッドでは、これは次の値が24px以上であることと同じです。

ピッチ = セル1辺 + gap

つまりセルを大きくする（＝Nを減らす）以外に、gap を広げるという打ち手があります。

ピッチ（セル1辺 + gap）	扱い
44px 以上	WCAG 2.5.5（AAA）を満たす。可能な限りこれを目指す
32px 〜 44px	許容。 盤面全体が画面に収まることを優先してよい
24px 〜 32px	許容するが、誤タップの取り消し手段が必須。 タップで仮選択（ハイライト）→ 44px以上の「確定」ボタンで確定する2段階操作、または直前の着手を取り消せるUIを提供する
24px 未満	WCAG 2.5.8（AA）を満たしません。 盤面のスクロール／ピンチズームを提供し、拡大した状態でピッチが24px以上になるようにする

32px のラインだけは対応する標準がなく、このプロジェクトの判断です（取り消し手段を必須にする目安として置いています）。

実行時に測って判断してください

iframeのサイズはポータル側で決まるため、ピッチの実寸はレンダリングするまで分かりません。ResizeObserver で盤面の実サイズを測り（§2 ④の実装例）、そこから求めてください。

設計時に最悪ケースを計算する

ポータルが保証する最小論理サイズは §2 の 308 × 480 です。ここから自分のレイアウトの左右の余白を引くと、盤面に使える幅が出ます。

盤面に使える幅 = 308 − (左右の余白の合計)
ピッチ         = (盤面に使える幅 + gap) ÷ N

npx hitsumabushi init --template board の雛形をそのまま使った場合の内訳です。

引かれるもの
body の padding: 8px	16px
カードの padding: 10px	20px
カードの border: 1px	2px
盤面に使える幅	270px

セル間の gap は 2px なので、たとえば N=13 なら:

ピッチ = (270 + 2) ÷ 13 ≈ 21px   → 24px を下回る（AAを満たさない）

⚠️ この 270px はテンプレートの余白に依存する値です。 レイアウトを変えたら計算し直してください。N をいくつにするかはゲーム側の判断で、ここで示しているのは「その N だと何が必須になるか」を先に知るための計算方法です。

⚠️ SDKはここに関与しません。 「セル1辺が何pxか」は上記のとおりゲーム側で測れますが、「だからどうするか」はゲームデザインの判断です。2段階タップに切り替える／盤面をズーム可能にする／そもそも盤面サイズを見直す、のどれが正解かはゲームによって違います。SDKが自動で切り替えると全ゲームが同じUXになるため、判断はゲームに委ねています。

npx hitsumabushi init --template board が生成する雛形には、実測セル1辺を受け取るフックが入っています。そこから先の挙動を書いてください。

あわせて実装すること:

• セルのヒット領域はセル境界いっぱいまで広げる（.cell { width: 100%; height: 100%; }。内側に margin を付けて実効領域を狭めない）
• 盤面に touch-action: manipulation を指定し、ダブルタップズームによる誤動作を抑止する
• 2段階操作にした場合、「確定」ボタン自体は 44 × 44 px 以上を維持する

---

2. モバイル・狭小画面対応（レスポンシブUIと情報密度制御）

要件

ポータル内の <iframe> は、PC・タブレット・スマートフォン・OBS（配信ソフト）など多様な環境で可変サイズ（幅・高さ）で埋め込まれます。
固定高さ（例: height: 420px;）の指定は避け、画面サイズに合わせて柔軟に伸縮するレイアウトを設計してください。

ゲームに与えられる論理サイズ（この表が正本です）

ポータルのレイアウトから実測した値です。

環境	画面サイズ	ゲームに与えられる領域
iPhone SE（縦）	320 × 568	308 × 510
iPhone SE2/3（縦）	375 × 667	363 × 609
iPhone 13（縦）	390 × 844	378 × 786
Pixel 7（縦）	412 × 915	400 × 857
iPhone SE（横）	568 × 320	556 × 480 ※
iPhone 13（横）	844 × 390	804 × 480 ※
ノートPC	1366 × 768	1326 × 648
デスクトップ	1920 × 1080	1360 × 960

ポータルが保証する最小論理サイズは 308 × 480 です。 グリッド盤面の「最悪ケースでピッチが何pxになるか」は、この値から設計時に計算できます（§1「例外：多セルのグリッド盤面」に計算方法があります）。

※ 横持ちスマホは本来 262〜270px しか取れませんが、ポータル側が min-height: 480px を設定しているため 480px が確保されます（そのぶんポータルのページがスクロールします）。

開発ハーネス（npx hitsumabushi dev）のプレビューは、この表のうち代表的な3つ（デスクトップ 1400×960 / モバイル 390×786 / OBS 1920×1080）を再現しています。

また、ボタンや手札カード等の要素が多いゲームでは、モバイル画面で押し潰されて可読性・操作性が損なわれないよう、適切な情報密度制御（レスポンシブ化）を行ってください。

推奨実装パターン

① ボタンの「テキスト省略＋アイコン化」（44 × 44 px との両立）

PCでは「アイコン＋説明テキスト」を表示し、モバイル幅（< 640px）や低画面高（< 560px）ではテキストを非表示にしてアイコンのみとすることで、横幅を大幅に節約できます。
※アイコン化した場合でも、第2項の 「タッチターゲット最小 44 × 44 px」 は必ず確保してください。

<!-- HTML構造: アイコンとテキストを分離 -->
<button class="action-btn" title="カードを引く" aria-label="カードを引く">
  <span class="btn-icon">🎴</span>
  <span class="btn-label">カードを引く</span>
</button>

/* PC・標準幅 */
.action-btn {
  min-width: 44px;
  min-height: 44px;
  padding: 8px 16px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 6px;
}

/* モバイル幅（640px以下）または低画面高（560px以下） */
@media (max-width: 640px), (max-height: 560px) {
  .action-btn .btn-label {
    display: none; /* テキストを隠してアイコンだけにする */
  }
  .action-btn {
    padding: 8px;
    width: 44px;  /* 44×44pxの正方形にコンパクト化 */
    height: 44px;
  }
}

② カード・トークンの可変スケーリング（clamp() の活用）

手札やコマが多いゲームでは、固定幅ではなく CSS の clamp() や min() を活用して画面幅に応じて滑らかに縮小させます。

/* 手札カードの可変スケール（最小36px〜最大64px、画面幅9vwに追従） */
.hand-card {
  width: clamp(36px, 9vw, 64px);
  aspect-ratio: 2 / 3;
  flex-shrink: 1;
}

③ プレイフィールドの自動伸縮（flex: 1）

ヘッダーやスコアボード、下部ステータスバーを flex-shrink: 0; とし、メインの盤面（アリーナ・ボード）を flex: 1; min-height: 150px; とすることで、上下見切れを起こさず安全に収まります。

.game-container {
  width: 100%;
  max-width: 640px;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: space-between;
}

.hud-header   { flex-shrink: 0; }
.play-arena   { flex: 1; min-height: 160px; width: 100%; } /* 自動伸縮 */
.status-bar   { flex-shrink: 0; }

④ N×N グリッド盤面の正方形フィット（ResizeObserver による実測）

五目並べ・オセロ・三目並べ・コネクトフォーなど「N×Nの正方形グリッド盤面」は定番ジャンルですが、高さが可変（事前に不明）なflexコンテナの中で、アスペクト比1:1を保ったまま最大サイズにフィットさせる必要があり、CSSだけでは安定しません。

CSSだけでは不安定になる理由:

手段	問題
aspect-ratio: 1 / 1	③ の flex: 1 コンテナ内では幅基準で高さが解決されるため、縦が足りない画面で盤面が下にはみ出す
vh / dvh 単位	iOS SafariのURLバー伸縮で変動し、回転直後も安定しない。iframe内ではポータル側のヘッダー高さも考慮できない
コンテナクエリ（cqw / cqh）	cqh は親に container-type: size が必要で、その親の高さが flex: 1 由来だと循環しやすい

推奨: ResizeObserver で親要素の実サイズを測り、px で指定する。

この3点セット（flex: 1 + min-height: 0 の入れ物 / ResizeObserver による実測 / セル1辺の整数px丸め）を実装済みの雛形が同梱されています。ゼロから書かずにこちらを使ってください。

npx hitsumabushi init --template board

実装時の注意:

• ResizeObserver は画面回転・OBSブラウザソースのサイズ変更・ポータル側のレイアウト変化すべてに追従します。window.resize イベントだけでは、親要素のサイズだけが変わるケースを取り逃します。
• 初期化直後やiframeが非表示の間は clientWidth / clientHeight が 0 になります。0 のときは何もしないガードを必ず入れてください（盤面が幅0で描画され、以後復帰しなくなります）。
• セルの内容（石・記号）は font-size も実寸に追従させます。fitBoard() の中で、セル1辺（snapped / SIZE）の 0.6 倍程度を board.style.fontSize に px 指定するのが簡単です。

---

3. スクロールバウンス抑止（iOS Safari 対策）

要件

iframe 内のコンテンツで iOS Safari の慣性スクロール（バウンス） が意図しない形で発生すると、
ゲームの操作感を著しく損ないます。ゲーム画面全体でスクロールバウンスを抑止してください。

実装例

/* ゲーム全体のバウンス抑止 */
html,
body {
  overscroll-behavior: none;          /* 標準仕様（Chrome / Firefox / Safari 16+） */
  overflow: hidden;                   /* ゲーム画面が固定レイアウトの場合 */
}

/* スクロール可能なサブ領域（スコアボード・チャット等）のみスクロール許可 */
.scrollable-area {
  overflow-y: auto;
  overscroll-behavior: contain;       /* 親要素へのスクロール伝播を防止 */
  -webkit-overflow-scrolling: touch;
}

// canvas のタッチスクロール干渉を防止
canvas.addEventListener('touchstart', (e) => e.preventDefault(), { passive: false });
canvas.addEventListener('touchmove',  (e) => e.preventDefault(), { passive: false });

---

4. 画面回転対応（スマートフォン向け案内）

要件

ゲームがランドスケープ（横向き）専用または一方向でのみ最適に動作する場合、
ユーザーに画面回転を促すガイダンスを表示してください。

推奨実装

/* ポートレート（縦向き）時に回転案内オーバーレイを表示 */
@media screen and (orientation: portrait) and (max-width: 768px) {
  .rotate-prompt      { display: flex; }
  .game-canvas-wrapper { display: none; }
}
@media screen and (orientation: landscape) {
  .rotate-prompt      { display: none; }
  .game-canvas-wrapper { display: block; }
}

.rotate-prompt {
  position: fixed;
  inset: 0;
  z-index: 9999;
  display: none;
  align-items: center;
  justify-content: center;
  background: rgba(10, 11, 16, 0.95);
  color: #f8fafc;
  text-align: center;
  padding: 24px;
}

.rotate-prompt__icon {
  font-size: 3rem;
  display: block;
  margin-bottom: 16px;
  animation: rotate-hint 2s ease-in-out infinite;
}

@keyframes rotate-hint {
  0%, 100% { transform: rotate(0deg);  }
  50%       { transform: rotate(90deg); }
}

<div class="rotate-prompt" aria-live="polite">
  <div>
    <span class="rotate-prompt__icon">📱↩️</span>
    <p>このゲームはスマートフォンを<strong>横向き</strong>にしてお楽しみください。</p>
  </div>
</div>

注意事項

• 縦向き・横向きの両方で自然に動作するゲームの場合、回転案内は不要です。
• screen.orientation.lock() API は iOS Safari では非対応のため、強制回転ではなくユーザーへの案内を推奨します。

---

5. オーディオ自動再生対応

要件

ブラウザのオーディオ自動再生ポリシーにより、ユーザー操作なしに音声を再生することはできません。
ゲームの BGM・効果音は必ずユーザー操作を契機に再生を開始してください。

ブラウザポリシーの概要

ブラウザ	自動再生ポリシー
Chrome 66+	ユーザーインタラクションなしの Audio.play() はブロック
Safari (iOS)	ユーザーインタラクションなしの再生は常にブロック
Firefox 66+	サイトのメディア自動再生設定に依存（デフォルト許可）

推奨実装パターン

// パターン1: 最初のユーザー操作で AudioContext を解除する
let audioContext = null;

function initAudio() {
  if (audioContext) return;
  audioContext = new (window.AudioContext || window.webkitAudioContext)();
  if (audioContext.state === 'suspended') audioContext.resume();
  playBGM();
}

document.addEventListener('click',      initAudio, { once: true });
document.addEventListener('touchstart', initAudio, { once: true });
document.addEventListener('keydown',    initAudio, { once: true });

// パターン2: <audio> 要素の非同期ガード
async function safePlay(audioElement) {
  try {
    await audioElement.play();
  } catch (err) {
    // NotAllowedError: ユーザー操作後に再試行
    console.warn('[Audio] 自動再生ブロック:', err.message);
  }
}

ミュートボタンの提供

配信者が BGM なしで配信する場合も考慮し、ミュート/音量調節 UI を必ず提供してください。
ミュートボタンのタッチターゲットは最小 44 × 44 px を確保すること。

OBS モードでの BGM の扱いは §8 OBS モード にあります。

---

6. iframe 通信（Hitsumabushi SDK との連携）

ポータルとの通信は window.postMessage / Hitsumabushi SDK を使います。イベント名・ペイロード形式・ 送信の上限値（サイズとレート）はすべて API リファレンス が正本です。本書では重複掲載しません。

⚠️ 毎フレーム送信は上限に張り付きます。 レート超過は無言で破棄されるため、 動かないのに理由が分からない不具合になります。送信は状態が変わったときだけにしてください。

---

7. サンドボックス（ストレージと CORS）

要件

ポータルはゲームの <iframe> に sandbox="allow-scripts" だけを付けます。ゲームは自分の配信元のオリジンではなく、不透明なオリジン（"null"）で動きます。そのため次の2つを守ってください。

• ブラウザのストレージと Cookie を使わない。 localStorage・sessionStorage・IndexedDB・document.cookie は例外になるか、保存されません。設定や進行状況をブラウザに残すことはできません。
• 配信元で Access-Control-Allow-Origin を返す。 次の読み込みは CORS で行われ、配信元がこのヘッダー（*）を返さないと失敗します。
  • <script type="module">（Vite などのビルドツールが出力する形）
  • crossorigin 属性の付いた <script> / <link rel="stylesheet">
  • fetch() / XMLHttpRequest（自分の配信元のファイルでも同じ）
  • Web フォント（@font-face）

コミュニティ枠（hitsumabushi-community-games）に投稿したゲームは、配信元がこのヘッダーを返すので対応は要りません。自分のサーバーで配信する場合は、ゲームの全ファイルにこのヘッダーを付けてください。

なぜ

コミュニティ枠のゲームは同じ配信元（同じオリジン）を共有しています。サンドボックスが無いと、あるゲームがほかのゲームの保存データや Cookie を読み書きできてしまいます。

ポップアップ（alert() / confirm() / window.open()）、フォームの送信、ポインターロック、トップレベルの遷移も許可していません。

確認の仕方

開発ハーネスの iframe にはサンドボックスがありません（検証 §4）。ハーネスで動いても、ストレージや CORS の問題は本番で初めて出ます。

---

8. OBS モード（配信画面への重ね合わせ）

要件

配信者は、ポータルを OBS のブラウザソースとして取り込み、ゲーム画面を自分の配信画面（立ち絵や背景）の上に重ねます。このときポータルは OBS モードになり、自分の背景・ヘッダー・広告を消します。ゲームの対戦フィールドや UI だけが浮かび上がるには、ゲームの側も次の2つをしてください。

• 背景を透明にする — html や body、全画面を覆う要素に付けている背景色を transparent にします。盤面・カード・ボタンなど、ゲームの中身の背景は残して構いません。
• BGM をミュートにする。

OBS モードの受け取り方

OBS モードかどうかは SDK が伝えます。

いつ	受け取り方
試合の開始時	onCreateMatch(config) / onStartMatch(config) の config.isObsMode
試合中に切り替わったとき	onObsModeChange(isObsMode)

onObsModeChange は最初から OBS モードのときに呼ばれるとは限りません。config.isObsMode も必ず見てください（API リファレンス §2）。

function applyObsMode(isObsMode) {
  document.body.classList.toggle('transparent', isObsMode);
  bgm.muted = isObsMode;
}

Hitsumabushi.init({
  onStartMatch: (config) => {
    applyObsMode(config.isObsMode);
    // ...
  },
  onObsModeChange: applyObsMode,
});

body.transparent { background-color: transparent !important; }

npx hitsumabushi init が置くテンプレートは、背景の透過に対応しています（BGM はテンプレートに無いため、鳴らすゲームが足してください）。

確認の仕方

開発ハーネス（npx hitsumabushi dev）の OBS モードの切り替えで、背景が透けて BGM が止まることを目で確かめてください。verify はこの項目を判定しません（検証 §5）。

---