diff --git a/packages/flutter/lib/src/painting/edge_insets.dart b/packages/flutter/lib/src/painting/edge_insets.dart
index c89edd9c86f..7e9532258ac 100644
--- a/packages/flutter/lib/src/painting/edge_insets.dart
+++ b/packages/flutter/lib/src/painting/edge_insets.dart
@@ -264,6 +264,13 @@ abstract class EdgeInsetsGeometry {
 /// Typically used for an offset from each of the four sides of a box. For
 /// example, the padding inside a box can be represented using this class.
 ///
+/// The [EdgeInsets] class specifies offsets in terms of visual edges, left,
+/// top, right, and bottom. These values are not affected by the
+/// [TextDirection]. To support both left-to-right and right-to-left layouts,
+/// consider using [EdgeInsetsDirectional], which is expressed in terms of
+/// _start_, top, _end_, and bottom, where start and end are resolved in terms
+/// of a [TextDirection] (typically obtained from the ambient [Directionality]).
+///
 /// ## Sample code
 ///
 /// Here are some examples of how to create [EdgeInsets] instances:
diff --git a/packages/flutter/lib/src/painting/fractional_offset.dart b/packages/flutter/lib/src/painting/fractional_offset.dart
index 61c2bbf78dd..fa333355a9b 100644
--- a/packages/flutter/lib/src/painting/fractional_offset.dart
+++ b/packages/flutter/lib/src/painting/fractional_offset.dart
@@ -180,6 +180,13 @@ abstract class FractionalOffsetGeometry {
 /// `FractionalOffset(0.5, 2.0)` represents a point half way across the [Size],
 /// below the bottom of the rectangle by the height of the [Size].
 ///
+/// The [FractionalOffset] class specifies offsets in terms of a distance from
+/// the top left, regardless of the [TextDirection]. To support both
+/// left-to-right and right-to-left layouts, consider using
+/// [FractionalOffsetDirectional], which is expressed in terms of an offset from
+/// the leading edge, which is then resolved in terms of a [TextDirection]
+/// (typically obtained from the ambient [Directionality]).
+///
 /// A variety of widgets use [FractionalOffset] in their configuration, most
 /// notably:
 ///