web-haptics

web-haptics（npm i web-haptics）をインストールし、次のルールに従ってアプリに触覚フィードバックを追加します。

パッケージ：web-haptics

リポジトリ：https://github.com/lochie/web-haptics | ライセンス：MIT | 依存関係ゼロ

Web Vibration API を使用します。サポートされていないプラットフォーム（デスクトップ）では、何もせずに処理を終了します。エラー処理や機能検出は必要ありません。

トリガーの種類

trigger() は次の文字列のいずれかを受け取ります（値が空の場合は、適切な「中程度」の衝撃がデフォルトで使用されます）。

通知（タスクの結果）：

• "success" -- フォームの保存、支払いの確認、アップロードの完了
• "warning" -- 破壊的な操作を実行する前、上限に近づいたとき、取り消せない手順
• "error" -- 入力検証の失敗、ネットワークエラー、権限の拒否

衝撃（物理的な衝突）：

• "light" -- 小さな切り替え、軽いタップ、ささいな操作
• "medium" -- ボタンの押下、カードが所定の位置にスナップ、所定の場所へのドロップ
• "heavy" -- 大きな状態変化、重い要素の着地、強く押す操作

選択（段階的な切り替え）：

• "selection" -- ピッカーのスクロール、ステッパーの増分、スライダーのデテント、セグメントの切り替え

フレームワークのインポート

React：

import { useWebHaptics } from "web-haptics/react";

const haptic = useWebHaptics();

<button onClick={() => haptic.trigger()}>Tap me</button>;

Vue：

<script setup>
import { useWebHaptics } from "web-haptics/vue";
const haptic = useWebHaptics();
</script>

<template>
  <button @click="haptic.trigger()">Tap me</button>
</template>

Svelte：

<script>
  import { createWebHaptics } from "web-haptics/svelte";
  import { onDestroy } from "svelte";
  const haptic = createWebHaptics();
  onDestroy(() => haptic.destroy());
</script>

<button on:click={() => haptic.trigger()}>Tap me</button>

Vanilla JS：

import { WebHaptics } from "web-haptics";

const haptics = new WebHaptics();
haptics.trigger(); // medium impact
haptics.trigger("success");

Next.js：useWebHaptics() を使用するコンポーネントには "use client" を追加します。 Nuxt/SvelteKit：ライブラリが SSR を処理するため、そのまま動作します。

トリガーのプリセットと defaultPatterns

名前付き文字列プリセットにはすべて、defaultPatterns 内に対応するオブジェクトがあります。文字列リテラルではなく値としてプリセットを渡す必要がある場合に使用してください。

import { WebHaptics, defaultPatterns } from 'web-haptics'

const haptics = new WebHaptics()
haptics.trigger(defaultPatterns.light)

上記に記載されていない追加のプリセット："soft"、"rigid"、"nudge"、"buzz"。使用可能なすべての値については、defaultPatterns を参照してください。

Apple HIG の設計ルール -- 必ず守ってください

1. 触覚フィードバックは補助として使用し、視覚フィードバックの代わりにしてはいけません。必ず視覚フィードバックと組み合わせてください。触覚フィードバックがなくても、UI は完全に機能する必要があります。
2. 因果関係を構築してください。触覚は、ユーザーの操作による直接的な物理的結果として感じられる必要があります。
3. 重要度に合わせて強度を調整してください。軽い操作には light/selection、標準的な操作には medium/success、大きな操作には heavy/error/warning を使用します。
4. 使いすぎないでください。タップのたびに振動すると、特別感がなくなります。意味のある場面に限って使用してください。
5. 完全に同期させてください。視覚的な変化が起きる瞬間に、触覚フィードバックを発生させます。
6. 慣例を尊重してください。success は肯定的、error は否定的、warning は注意喚起、selection は段階的なクリック感に限って使用します。
7. 非同期処理では、結果が届いたときに、視覚的な状態変化と同期させてトリガーします。

   try {
     await submit();
     haptic.trigger("success");
   } catch {
     haptic.trigger("error");
   }
   

操作と種類のクイックリファレンス

プライマリボタンのタップ = "medium" | セカンダリボタン = "light" フォームの成功 = "success" | 入力検証エラー = "error" | ネットワークエラー = "error" トグルスイッチ = "light" | 確認前の削除 = "warning" ピッカー／ホイール = "selection" | スライダーのデテント = "selection" | タブの切り替え = "selection" ドラッグ＆ドロップでのスナップ = "medium" | 長押し = "heavy" | モーダルの表示 = "medium" プルして更新のしきい値 = "light" | スワイプで閉じるしきい値 = "light" 支払いの確認 = "success"

アンチパターン -- 避けてください

• タップのたびに触覚フィードバックを発生させる（疲労につながります）
• エラーではない場面で "error" を使用する（慣例に反します）
• 視覚フィードバックなしで触覚フィードバックを発生させる（一部のデバイスでは振動できません）
• ページの読み込み時や受動的なスクロール時に触覚フィードバックを発生させる（煩わしくなります）
• ささいな操作に "heavy" を使用する（唐突に感じられます）
• 長時間の連続振動（ウェブの触覚フィードバックは短い一時的なパルスです）

実装する前に、ユーザーに確認してください：

• 対象とするインタラクティブ要素
• 共有コンポーネントのレベルで追加するか、個々の呼び出し箇所に追加するか