docs(spindle-ui): 通知系コンポーネントの説明と使い分け、事例をアップデート

packages/spindle-ui/src/InlineNotification/InlineNotification.stories.mdx

@@ -30,7 +30,10 @@ import UserNotificationTypes from '../../storybook/UserNotificationTypes.mdx';
   code={`<link rel="stylesheet" href="https://unpkg.com/@openameba/spindle-ui/InlineNotification/InlineNotification.css">`}
 />
 
-InlineNotificationコンポーネントは、ユーザーのアクションに対してお知らせをする際に利用します。Toast, SnackBarのようにコンテンツに重ねての表示ではなく、コンテンツと同じ階層での表示になります。
+InlineNotificationコンポーネントは、ユーザーの操作を中断せず、システムやUIの状態を簡易的にユーザーへ連絡するために用います。重要なメッセージや、告知や新機能リリースなどの、その画面の目的とは異なる簡易的なお知らせなどに役立ちます。
+
+
+ユーザーのアクションに対してお知らせをする際に利用します。Toast, SnackBarのようにコンテンツに重ねての表示ではなく、コンテンツと同じ階層での表示になります。
 
 また、エラー内容を表示するForm/InvalidMessageコンポーネントとは異なり、フォームに紐づかない形で提供されます。
 

packages/spindle-ui/src/SnackBar/SnackBar.stories.mdx

@@ -116,9 +116,7 @@ export const MultiActivateButton = ({ offset, icon, position }) => {
 
 <Meta title="SnackBar" component={SnackBar} />
 
-SnackBarコンポーネントは、利用者に一時的なお知らせをする際に利用します。画面上に複数表示できます。SnackBarは自動で消えてしまうため、見落とされても影響のない「重要ではないお知らせ」に用います。利用する際には、その他により適切な手段がないか必ず確認してください。
-
-「重要なお知らせ」とは何かは別途まとめる予定です。
+SnackBarコンポーネントは、ユーザーの操作を邪魔しないよう**非同期的にシステムやUIのフィードバックをユーザーへ通知する**ために用います。画面のレイアウトや状態に影響を与えないので、特にユーザーへの影響値を最小限にできます。一方で、一定時間で消滅するため、ユーザーが見落としてしまっても同一の内容を確認できる**代替手段がある場合に使う**必要があります。（詳しい事例は「[利用時に注意してほしいこと](#利用時に注意してほしいこと)」参照）
 
 <UserNotificationTypes />
 
@@ -463,11 +461,16 @@ SnackBarコンポーネントは、利用者に一時的なお知らせをする
 
 ## 利用時に注意してほしいこと
 
-- SnackBarは自動で消えてしまうため、見落とされても影響のない、「重要ではないお知らせ」に用います
-- アイコンの設定は利用者に委ねられていますが、基本的には設定します。**`information`のみアイコンを外すことができます。**
+- SnackBarは自動で消えてしまうため、ユーザーが見落としてしまっても同一の内容を確認できる代替手段がある場合に使います
+  - 例：メッセージ送信時、送信フォームが閉じられ、送信完了後に「メッセージを送信しました」のSnackBar通知が表示される。SnackBar上には「確認」ボタンも表示されている。確認ボタンを押すと送信したメッセージの詳細を確認できる
+    - ユーザーは確認ボタンを押さなくてもタスクは完了している
+    - 送信フォームが閉じられ、エラーが表示されないことで成功していることを認知できる（通知の代替手段になり得る）
+    - 送信履歴からユーザーはいつでもメッセージの送信が成功していること、メッセージの詳細内容を確認できる（SnackBar以外の代替手段がある）
+- アイコンの設定は利用者に委ねられていますが、基本的には設定します。**`information`のみアイコンを外せます。**
 - 任意のボタンを設定できます。システム上では制御しませんが、5文字以上を設定してはいけません。またボタンは1つ以上追加しないでください。
 - SnackBarでは最大3行まで表示されます。320px以下の画面では4行まで表示されます。超える部分は切られます。
 - モバイル表示ではbottom-center固定になるので注意してください。
+- 自動的に消えてしまうため、画面内で的確に認知できる必要があります。画面拡大時にもSnackBar内の情報が見切れることのないよう注意してください（参考：[1.4.10 リフローできる - Ameba Accessibility Guidelines](https://a11y-guidelines.ameba.design/1/4/10)）
 - このコンポーネントでは関与しませんが、ライブリージョンをアプリケーションで実装してください（参考：[実装方法 - 4.1.3 コンテンツの変更をユーザーに知らせる - Ameba Accessibility Guidelines](https://a11y-guidelines.ameba.design/4/1/3/#%E5%AE%9F%E8%A3%85%E6%96%B9%E6%B3%95)）
 - ライブリージョンは次のように実装します。 `html` 側に `aria-live="polite"` 及び `role="status"` を持つ要素を予め埋め込んでおき、この要素にコンテンツを動的に挿入することで、スクリーンリーダーが自動でコンテンツを読み上げてくれます。
 

packages/spindle-ui/src/Toast/Toast.stories.mdx

@@ -112,9 +112,7 @@ export const MultiActivateButton = ({ offset, icon, position }) => {
 
 <Meta title="Toast" component={Toast} />
 
-Toastコンポーネントは、利用者に一時的なお知らせをする際に利用します。画面上に複数表示できます。Toastは自動で消えてしまうため、見落とされても影響のない「重要ではないお知らせ」に用います。利用する際には、その他により適切な手段がないか必ず確認してください。
-
-「重要なお知らせ」とは何かは別途まとめる予定です。
+Toastコンポーネントは、ユーザーの操作を邪魔しないよう**非同期的にシステムやUIのフィードバックをユーザーへ通知する**ために用います。画面のレイアウトや状態に影響を与えないので、特にユーザーへの影響値を最小限にできます。一方で、一定時間で消滅するため、ユーザーが見落としてしまっても同一の内容を確認できる**代替手段がある場合に使う**必要があります。（詳しい事例は「[利用時に注意してほしいこと](#利用時に注意してほしいこと)」参照）
 
 <UserNotificationTypes />
 
@@ -266,24 +264,15 @@ Toastコンポーネントは、利用者に一時的なお知らせをする際
 
 ## 利用時に注意してほしいこと
 
-<Description>
-  -
-  Toastは自動で消えてしまうため、見落とされても影響のない、「重要ではないお知らせ」に用います
-</Description>
-<Description>
-  - アイコンの設定は利用者に委ねられていますが、基本的には設定します。**`information`のみアイコンを外すことができます。**
-</Description>
-<Description>
-  - `z-index`はdefaultでは`1`になっていますが、必要に応じて`--Toast-z-index`を設定してください
-</Description>
-<Description>
-  -
-  このコンポーネントでは関与しませんが、ライブリージョンをアプリケーションで実装してください（参考：[実装方法 - 4.1.3 コンテンツの変更をユーザーに知らせる - Ameba Accessibility Guidelines](https://a11y-guidelines.ameba.design/4/1/3/#%E5%AE%9F%E8%A3%85%E6%96%B9%E6%B3%95)）
-</Description>
-<Description>
-  -
-  ライブリージョンは次のように実装します。 `html` 側に `aria-live="polite"` 及び `role="status"` を持つ要素を予め埋め込んでおき、この要素にコンテンツを動的に挿入することで、スクリーンリーダーが自動でコンテンツを読み上げてくれます。
-</Description>
+- Toastは自動で消えてしまうため、ユーザーが見落としてしまっても同一の内容を確認できる代替手段がある場合に使います
+  - 例：「URLをコピーしました」のToast通知と並行して、コピーボタンのマークがチェックマーク付きのアイコンに切り替わっている
+    - ボタンの表示が切り替わることで、完了を認知できる（通知の代替手段になり得る）
+- アイコンの設定は利用者に委ねられていますが、基本的には設定します。**`information`のみアイコンを外すことができます**
+- `z-index`はdefaultでは`1`になっていますが、必要に応じて`--Toast-z-index`を設定してください
+- 自動的に消えてしまうため、画面内で的確に認知できる必要があります。画面拡大時にもToast内の情報が見切れることのないよう注意してください（参考：[1.4.10 リフローできる - Ameba Accessibility Guidelines](https://a11y-guidelines.ameba.design/1/4/10)）
+-
+このコンポーネントでは関与しませんが、ライブリージョンをアプリケーションで実装してください（参考：[実装方法 - 4.1.3 コンテンツの変更をユーザーに知らせる - Ameba Accessibility Guidelines](https://a11y-guidelines.ameba.design/4/1/3/#%E5%AE%9F%E8%A3%85%E6%96%B9%E6%B3%95)）
+- ライブリージョンは次のように実装します。 `html` 側に `aria-live="polite"` 及び `role="status"` を持つ要素を予め埋め込んでおき、この要素にコンテンツを動的に挿入することで、スクリーンリーダーが自動でコンテンツを読み上げてくれます
 
 <Source
   code={`

packages/spindle-ui/storybook/UserNotificationTypes.mdx

@@ -1,10 +1,13 @@
 ## ユーザーへの通知の種別
 
-ユーザーに画面内で通知する手段としてToast、SnackBar、InlineNotificationコンポーネントがあります。画面内で完結せず、遷移させるべき状況もあります。現状下記のように使い分けています。
+ユーザーに画面内で通知する手段としてToast、SnackBar、InlineNotification、Dialogコンポーネントがあります。画面内で完結せず、遷移させるべき状況もあります。現状下記のように使い分けています。
+
+なお、ToastとSnackBarは自動で消えてしまうため、**その通知内容を確認できる他の手段がある場合にのみ**利用できます。「コンテンツの確実な伝達」ではなく「ユーザーの行動を中断することなく示唆する」ことを目的として用います。
 
 | 選択肢 | 用途 | テキストの長さ | 追加のアクション | 自動で消える秒数 | 表示位置 |
 | ---- | ---- | ---- | ---- | ---- | ---- |
-| [Toast](/docs/toast--information) | 更新処理の**成功を伝える**<br />**見落としても支障がないもの** | 1行 | なし | 4秒 | フローティング<br />（画面上下の中央のみ） |
-| [SnackBar](/docs/snackbar--information) | **読んでは欲しい訴求** | 3行まで | あり | 10秒 | フローティング<br />（画面上下の左・右・中央） |
-| [InlineNotification](/docs/inlinenotification--information) | 更新処理の**失敗を伝える**<br />**ユーザーが追加でアクションする必要があるもの** | 制限なし | あり | 消えない | ページに埋め込む必要があり、レイアウトに影響を与える |
+| [Toast](/docs/toast--information) | 更新処理の**成功を伝える**<br />完了タイミングに気づくための最低限のフィードバック | 1行 | なし | 4秒 | フローティング<br />（画面上下の中央のみ） |
+| [SnackBar](/docs/snackbar--information) | ユーザーにとって読む価値があるもの<br />ユーザーが追加のアクションを実行しなくても完結するもの | 3行まで | あり | 10秒 | フローティング<br />（画面上下の左・右・中央） |
+| [InlineNotification](/docs/inlinenotification--information) | 更新処理の**失敗を伝える**<br />ユーザーが追加のアクションを実行すると通知の役割を果たすもの | 制限なし | あり | 消えない | ページに埋め込む必要があり、レイアウトに影響を与える |
+| [Dialog](/docs/dialog--normal) | ユーザーのメインタスクを中断して確認してもらうべき重要な通知 | 制限なし | あり | 消えない | モーダル |
 | 画面外へ遷移させる | 一連の動作にゴールがある（登録時の完了画面など）<br />「元の画面に戻る」動作をさせたい時 | 制限なし | 制限なし | 消えない | 別ページ |