From d7e1f03ee0c2aaebbc99b415efefdb19d4e1c261 Mon Sep 17 00:00:00 2001
From: Alejandro Santiago <me@alestiago.com>
Date: Wed, 13 Nov 2024 20:37:22 +0000
Subject: [PATCH] docs: include Human Interface haptic information in
 HapticFeedback (#158587)

## Description

Adding reference to the Human Interface documentation about Haptics in the `HapticFeedback` docs.

The Human Haptic Guidelines documentation are excellent since they provide visualizations that show how these different haptics actually are with some interactive demos, for example with Impact haptics (see image below). Such helps developers decide what haptic to go for and understand when they should be used.

<img width="675" alt="Screenshot 2024-11-13 at 15 13 10" src="https://github.com/user-attachments/assets/909240d3-1981-4e25-9bed-b3b52154e662">
---
 .../lib/src/services/haptic_feedback.dart      | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/packages/flutter/lib/src/services/haptic_feedback.dart b/packages/flutter/lib/src/services/haptic_feedback.dart
index e3aad6c28e3..7c0fa8af55d 100644
--- a/packages/flutter/lib/src/services/haptic_feedback.dart
+++ b/packages/flutter/lib/src/services/haptic_feedback.dart
@@ -9,6 +9,10 @@ import 'system_channels.dart';
 ///
 /// This API is intentionally terse since it calls default platform behavior. It
 /// is not suitable for precise control of the system's haptic feedback module.
+///
+/// See also:
+///
+/// * [Human Interface Haptics Guidelines](https://developer.apple.com/design/human-interface-guidelines/playing-haptics)
 abstract final class HapticFeedback {
   /// Provides vibration haptic feedback to the user for a short duration.
   ///
@@ -28,6 +32,12 @@ abstract final class HapticFeedback {
   /// below 10.
   ///
   /// On Android, this uses `HapticFeedbackConstants.VIRTUAL_KEY`.
+  ///
+  /// {@template flutter.services.HapticFeedback.impact}
+  /// See also:
+  ///
+  /// * [Human Interface Selection Playing Impact Haptic](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Impact)
+  /// {@endtemplate}
   static Future<void> lightImpact() async {
     await SystemChannels.platform.invokeMethod<void>(
       'HapticFeedback.vibrate',
@@ -42,6 +52,8 @@ abstract final class HapticFeedback {
   /// below 10.
   ///
   /// On Android, this uses `HapticFeedbackConstants.KEYBOARD_TAP`.
+  ///
+  /// {@macro flutter.services.HapticFeedback.impact}
   static Future<void> mediumImpact() async {
     await SystemChannels.platform.invokeMethod<void>(
       'HapticFeedback.vibrate',
@@ -57,6 +69,8 @@ abstract final class HapticFeedback {
   ///
   /// On Android, this uses `HapticFeedbackConstants.CONTEXT_CLICK` on API levels
   /// 23 and above. This call has no effects on Android API levels below 23.
+  ///
+  /// {@macro flutter.services.HapticFeedback.impact}
   static Future<void> heavyImpact() async {
     await SystemChannels.platform.invokeMethod<void>(
       'HapticFeedback.vibrate',
@@ -70,6 +84,10 @@ abstract final class HapticFeedback {
   /// This call has no effects on iOS versions below 10.
   ///
   /// On Android, this uses `HapticFeedbackConstants.CLOCK_TICK`.
+  ///
+  /// See also:
+  ///
+  /// * [Human Interface Selection Playing Selection Haptics](https://developer.apple.com/design/human-interface-guidelines/playing-haptics#Selection)
   static Future<void> selectionClick() async {
     await SystemChannels.platform.invokeMethod<void>(
       'HapticFeedback.vibrate',