前回でトップの UX を詰めました

今回は 検索の中身 です
トップの黄ヒーロー内にも、ナビの虫めがねにも検索窓はあります
見た目はデザインを載せた回の段階で決まっていた ので、今回いきなりデザインから入る回ではありません

静的サイトの制約のなかで、検索をどう実装するか を詰める回になります

静的サイトで検索を実装するときの前提

サイトは Vercel 上の静的配信です
DB もランタイム API もないので、検索のたびにサーバや外部の検索サービスへ問い合わせる 形は最初から候補にしませんでした
データはサイトと一緒に配信し、ブラウザ内かビルド時 で処理する方式に絞ります

候補はだいたい2つです

方式	仕組み	向いているタイミング
Fuse.js	`entries.json` をブラウザに載せてファジー検索	件数が少ない今、実装が速い
Pagefind	ビルド時に静的インデックスを生成	件数増・日本語 index が要る段階

まず Fuse.js → 増えたら Pagefind の段階移行を採用しました
UI は共通化しておき、中身だけ差し替え可能にしています

どちらも クライアント完結 なので、将来きつめの CSP を載せても検索が突然動かなくなる、といった事態は避けやすいです

補足 — CSP とは

CSP（Content Security Policy） は、ブラウザに「このページのスクリプトはどこへ通信してよいか」を伝える HTTP ヘッダです
厳しめにすると、検索のたびに別ドメインの API を呼ぶ実装はブロックされがちです

このサイトは当時、本番に CSP ヘッダは載せていません
それでも 後からセキュリティを固める余地 を残したい、という意味で頭に置いていました

検索語を URL で渡しても、結果が変わらない

トップやナビの検索窓は、キーワードを入れて送信すると /search?q=キーワード のような URL に遷移します
? 以降は クエリ（検索語などを URL に載せる部分） で、q は検索語用のパラメータ名です

何が起きていたか

実装前は、検索結果を ビルド時（SSG） に作っていました
そのため次のような状態でした

本番・プレビューで ?q=... を付けても ページ内容が変わらない
開発環境でも /search と /search/ の末尾スラッシュの差で、クエリが落ちることがあった

原因

静的ビルドは検索ページを 1種類の HTML として書き出します
ビルドの瞬間に「いま q が何か」は分からないので、あとから /search?q=Slack を開いても、返ってくる HTML は /search?q=別の語 と同じです
URL の検索語を読む処理が、そもそもページ側にありませんでした

解決策 — 結果はブラウザで描画する

検索結果をビルド時に作らず、ページを開いたあと JavaScript で作る ように変えました
流れは次のとおりです

SSG では枠だけ — 検索フォームと、結果を入れる空の領域だけ HTML に残す
entries.json をページに埋め込む — あるあるデータを同じページから読めるようにする
search-page.ts が URL の q を読む — 送信後の /search?q=... から検索語を取り出す
取り出した語でマッチした行を DOM に描画 — 件数・タイトル・一覧を書き換える

ここまでが「URL の検索語で結果が変わる」ための本体です
どうマッチさせるか（ファジー検索・重み付け） は次の Fuse.js の話になります
Fuse.js 以前に、まずこの クライアント描画 を入れないと、検索窓は見た目だけの「飾り」になります

Fuse.js Phase 1 — マッチングの中身

上の手順 4 の マッチング に fuse.js を使いました
ファイル構成は次のとおりです

ファイル	役割
`search-fuse.ts`	重み付け keys（title 0.35, tags 0.25, category 0.15, symptom/cause/fix 各 0.1/0.08/0.07）, threshold 0.35
`search-page.ts`	URL `q` を読み取り結果描画、静的ビルドでも動作
`search.astro`	entries JSON を `application/json` で埋め込み

ヒーロー・ナビ・タグ空状態のリンクも /search/ に統一 しました

検索対象フィールドは title / symptom / cause / fix / category / tags（サイト本番スキーマの fix キーに合わせる）

開発は docker compose 正規です
依存追加後は image rebuild が要ります——ここを忘れると「動かない」が長引きます

docker compose up --build
cd web && npm run build

ビルド後、検索クエリ付き URL で件数と document.title の更新を確認しました

結果画面の UI — 2ゾーンからサイト言語へ

Fuse.js を入れたあとも、結果画面の見た目はまだモック寄りで、操作エリア（カード面）＋結果エリア（薄グレー） の2ゾーン色分け自体は正しいのですが、外枠カード＋黄 3px ライン＋矩形フォームの組み合わせで 箱の中の箱 感が出ていました

※ スクショは一般的な PC ブラウザの1画面分で切り出しています

リデザインで方針を整理しました

項目	変更
2ゾーン	維持、上＝操作（ページ背景）、下＝結果（muted 全幅バンド）
外枠カード	廃止
検索フォーム	トップと同じ `hero-search` ピル型（黒枠・黒ボタン）
結果行	トップ `AruaruCard` 系の `.search-hit`（黄上線・症状1行）
黄 3px 境界	削除、背景差のみでゾーン分離

黄帯はトップ専用 — 検索ページは「探す」役割です
操作と結果の切り分けは前回のトップ UX 調整と同じ発想です

Pagefind への移行は まだ未実施 です
件数と日本語 index の挙動を見てからにします

今回の HACK+PLUS

見た目先行の検索 UI に、静的サイト向けのロジックを載せた 回でした

HACK（新しい発見）

SSG だけでは URL の検索語（?q=...）を反映できない — クライアント描画に切り替えるのが早い
Fuse.js は件数が少ない静的サイト向け — 外部 API なしでファジー＋重み付けが足せる

PLUS（ハマりどころ・次の一手）

詳細ページも黄ヒーローだと 読むとき「またトップ？」 と感じる — ページ役割の見直しが次