8 files changed, 169 insertions, 21 deletions
diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
index 2fcf5704a4..6d1e11c7c5 100644
--- a/platform/darwin/docs/guides/For Style Authors.md.ejs
+++ b/platform/darwin/docs/guides/For Style Authors.md.ejs
@@ -286,6 +286,14 @@ For padding attributes, note that the arguments to
 `EdgeInsets(top:left:bottom:right:)` in Swift are specified in counterclockwise
 order, in contrast to the clockwise order defined by the style specification.
 
+<% if (macOS) { -%>
+Additionally, on macOS, a screen coordinate of (0, 0) is located at the
+lower-left corner of the screen. Therefore, a positive `CGVector.dy` means an
+offset or translation upward, while a negative `CGVector.dy` means an offset or
+translation downward. This is the reverse of how `CGVector` is interpreted on
+iOS.
+
+<% } -%>
 ## Filtering sources
 
 You can filter a shape or vector source by setting the
diff --git a/platform/darwin/scripts/generate-style-code.js b/platform/darwin/scripts/generate-style-code.js
index a5fff0322d..418153591a 100644
--- a/platform/darwin/scripts/generate-style-code.js
+++ b/platform/darwin/scripts/generate-style-code.js
@@ -273,7 +273,7 @@ global.describeValue = function (value, property, layerType) {
                     return 'an `NSValue` object containing an `NSEdgeInsets` or `UIEdgeInsets` struct set to' + ` ${value[0]}${units} on the top, ${value[3]}${units} on the left, ${value[2]}${units} on the bottom, and ${value[1]}${units} on the right`;
                 case 'offset':
                 case 'translate':
-                    return 'an `NSValue` object containing a `CGVector` struct set to' + ` ${value[0]}${units} from the left and ${value[1]}${units} from the top`;
+                    return 'an `NSValue` object containing a `CGVector` struct set to' + ` ${value[0]}${units} rightward and ${value[1]}${units} downward`;
                 default:
                     return 'the array `' + value.join('`, `') + '`';
             }
@@ -420,6 +420,17 @@ ${iosComment}${decl}
 #else
 ${macosComment}${decl}
 #endif`;
+    })
+        // Do the same for CGVector-typed properties.
+        .replace(/(\/\*\*(?:\*[^\/]|[^*])*?\bCGVector\b[\s\S]*?\*\/)(\s*.+?;)/g,
+                       (match, comment, decl) => {
+        let macosComment = comment.replace(/\bdownward\b/g, 'upward');
+        return `\
+#if TARGET_OS_IPHONE
+${comment}${decl}
+#else
+${macosComment}${decl}
+#endif`;
     });
 }
 
diff --git a/platform/darwin/src/MGLCircleStyleLayer.h b/platform/darwin/src/MGLCircleStyleLayer.h
index 87839467a9..7d1da0ca68 100644
--- a/platform/darwin/src/MGLCircleStyleLayer.h
+++ b/platform/darwin/src/MGLCircleStyleLayer.h
@@ -144,21 +144,37 @@ typedef NS_ENUM(NSUInteger, MGLCircleTranslationAnchor) {
 
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *circlePitchScale __attribute__((unavailable("Use circleScaleAlignment instead.")));
 
+#if TARGET_OS_IPHONE
 /**
  The geometry's offset.
  
  This property is measured in points.
  
  The default value of this property is an `MGLStyleValue` object containing an
- `NSValue` object containing a `CGVector` struct set to 0 points from the left
- and 0 points from the top. Set this property to `nil` to reset it to the
- default value.
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points downward. Set this property to `nil` to reset it to the default value.
  
  This attribute corresponds to the <a
  href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-circle-translate"><code>circle-translate</code></a>
  layout property in the Mapbox Style Specification.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *circleTranslation;
+#else
+/**
+ The geometry's offset.
+ 
+ This property is measured in points.
+ 
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points upward. Set this property to `nil` to reset it to the default value.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-circle-translate"><code>circle-translate</code></a>
+ layout property in the Mapbox Style Specification.
+ */
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *circleTranslation;
+#endif
 
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *circleTranslate __attribute__((unavailable("Use circleTranslation instead.")));
 
diff --git a/platform/darwin/src/MGLFillStyleLayer.h b/platform/darwin/src/MGLFillStyleLayer.h
index 8bdf177a30..16e1673a44 100644
--- a/platform/darwin/src/MGLFillStyleLayer.h
+++ b/platform/darwin/src/MGLFillStyleLayer.h
@@ -118,21 +118,37 @@ typedef NS_ENUM(NSUInteger, MGLFillTranslationAnchor) {
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSString *> *fillPattern;
 
+#if TARGET_OS_IPHONE
 /**
  The geometry's offset.
  
  This property is measured in points.
  
  The default value of this property is an `MGLStyleValue` object containing an
- `NSValue` object containing a `CGVector` struct set to 0 points from the left
- and 0 points from the top. Set this property to `nil` to reset it to the
- default value.
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points downward. Set this property to `nil` to reset it to the default value.
  
  This attribute corresponds to the <a
  href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-fill-translate"><code>fill-translate</code></a>
  layout property in the Mapbox Style Specification.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *fillTranslation;
+#else
+/**
+ The geometry's offset.
+ 
+ This property is measured in points.
+ 
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points upward. Set this property to `nil` to reset it to the default value.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-fill-translate"><code>fill-translate</code></a>
+ layout property in the Mapbox Style Specification.
+ */
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *fillTranslation;
+#endif
 
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *fillTranslate __attribute__((unavailable("Use fillTranslation instead.")));
 
diff --git a/platform/darwin/src/MGLLineStyleLayer.h b/platform/darwin/src/MGLLineStyleLayer.h
index f25acecf97..99bbaab52d 100644
--- a/platform/darwin/src/MGLLineStyleLayer.h
+++ b/platform/darwin/src/MGLLineStyleLayer.h
@@ -249,21 +249,37 @@ typedef NS_ENUM(NSUInteger, MGLLineTranslationAnchor) {
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSString *> *linePattern;
 
+#if TARGET_OS_IPHONE
 /**
  The geometry's offset.
  
  This property is measured in points.
  
  The default value of this property is an `MGLStyleValue` object containing an
- `NSValue` object containing a `CGVector` struct set to 0 points from the left
- and 0 points from the top. Set this property to `nil` to reset it to the
- default value.
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points downward. Set this property to `nil` to reset it to the default value.
  
  This attribute corresponds to the <a
  href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-line-translate"><code>line-translate</code></a>
  layout property in the Mapbox Style Specification.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslation;
+#else
+/**
+ The geometry's offset.
+ 
+ This property is measured in points.
+ 
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points upward. Set this property to `nil` to reset it to the default value.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-line-translate"><code>line-translate</code></a>
+ layout property in the Mapbox Style Specification.
+ */
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslation;
+#endif
 
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *lineTranslate __attribute__((unavailable("Use lineTranslation instead.")));
 
diff --git a/platform/darwin/src/MGLSymbolStyleLayer.h b/platform/darwin/src/MGLSymbolStyleLayer.h
index 278c582c93..5943f2327e 100644
--- a/platform/darwin/src/MGLSymbolStyleLayer.h
+++ b/platform/darwin/src/MGLSymbolStyleLayer.h
@@ -331,17 +331,31 @@ typedef NS_ENUM(NSUInteger, MGLTextTranslationAnchor) {
 
 @property (nonatomic, null_resettable) MGLStyleValue<NSString *> *iconImage __attribute__((unavailable("Use iconImageName instead.")));
 
+#if TARGET_OS_IPHONE
+/**
+ Offset distance of icon from its anchor.
+ 
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 rightward and 0
+ downward. Set this property to `nil` to reset it to the default value.
+ 
+ This property is only applied to the style if `iconImageName` is non-`nil`.
+ Otherwise, it is ignored.
+ */
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *iconOffset;
+#else
 /**
  Offset distance of icon from its anchor.
  
  The default value of this property is an `MGLStyleValue` object containing an
- `NSValue` object containing a `CGVector` struct set to 0 from the left and 0
- from the top. Set this property to `nil` to reset it to the default value.
+ `NSValue` object containing a `CGVector` struct set to 0 rightward and 0
+ upward. Set this property to `nil` to reset it to the default value.
  
  This property is only applied to the style if `iconImageName` is non-`nil`.
  Otherwise, it is ignored.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *iconOffset;
+#endif
 
 /**
  If true, text will display without their corresponding icons when the icon
@@ -747,20 +761,35 @@ typedef NS_ENUM(NSUInteger, MGLTextTranslationAnchor) {
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *textLineHeight;
 
+#if TARGET_OS_IPHONE
 /**
  Offset distance of text from its anchor.
  
  This property is measured in ems.
  
  The default value of this property is an `MGLStyleValue` object containing an
- `NSValue` object containing a `CGVector` struct set to 0 ems from the left and
- 0 ems from the top. Set this property to `nil` to reset it to the default
- value.
+ `NSValue` object containing a `CGVector` struct set to 0 ems rightward and 0
+ ems downward. Set this property to `nil` to reset it to the default value.
+ 
+ This property is only applied to the style if `text` is non-`nil`. Otherwise,
+ it is ignored.
+ */
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *textOffset;
+#else
+/**
+ Offset distance of text from its anchor.
+ 
+ This property is measured in ems.
+ 
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 ems rightward and 0
+ ems upward. Set this property to `nil` to reset it to the default value.
  
  This property is only applied to the style if `text` is non-`nil`. Otherwise,
  it is ignored.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *textOffset;
+#endif
 
 /**
  If true, icons will display without their corresponding text when the text
@@ -946,15 +975,15 @@ typedef NS_ENUM(NSUInteger, MGLTextTranslationAnchor) {
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *iconOpacity;
 
+#if TARGET_OS_IPHONE
 /**
  Distance that the icon's anchor is moved from its original placement.
  
  This property is measured in points.
  
  The default value of this property is an `MGLStyleValue` object containing an
- `NSValue` object containing a `CGVector` struct set to 0 points from the left
- and 0 points from the top. Set this property to `nil` to reset it to the
- default value.
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points downward. Set this property to `nil` to reset it to the default value.
  
  This property is only applied to the style if `iconImageName` is non-`nil`.
  Otherwise, it is ignored.
@@ -964,6 +993,25 @@ typedef NS_ENUM(NSUInteger, MGLTextTranslationAnchor) {
  layout property in the Mapbox Style Specification.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *iconTranslation;
+#else
+/**
+ Distance that the icon's anchor is moved from its original placement.
+ 
+ This property is measured in points.
+ 
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points upward. Set this property to `nil` to reset it to the default value.
+ 
+ This property is only applied to the style if `iconImageName` is non-`nil`.
+ Otherwise, it is ignored.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-icon-translate"><code>icon-translate</code></a>
+ layout property in the Mapbox Style Specification.
+ */
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *iconTranslation;
+#endif
 
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *iconTranslate __attribute__((unavailable("Use iconTranslation instead.")));
 
@@ -1078,15 +1126,15 @@ typedef NS_ENUM(NSUInteger, MGLTextTranslationAnchor) {
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSNumber *> *textOpacity;
 
+#if TARGET_OS_IPHONE
 /**
  Distance that the text's anchor is moved from its original placement.
  
  This property is measured in points.
  
  The default value of this property is an `MGLStyleValue` object containing an
- `NSValue` object containing a `CGVector` struct set to 0 points from the left
- and 0 points from the top. Set this property to `nil` to reset it to the
- default value.
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points downward. Set this property to `nil` to reset it to the default value.
  
  This property is only applied to the style if `text` is non-`nil`. Otherwise,
  it is ignored.
@@ -1096,6 +1144,25 @@ typedef NS_ENUM(NSUInteger, MGLTextTranslationAnchor) {
  layout property in the Mapbox Style Specification.
  */
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *textTranslation;
+#else
+/**
+ Distance that the text's anchor is moved from its original placement.
+ 
+ This property is measured in points.
+ 
+ The default value of this property is an `MGLStyleValue` object containing an
+ `NSValue` object containing a `CGVector` struct set to 0 points rightward and 0
+ points upward. Set this property to `nil` to reset it to the default value.
+ 
+ This property is only applied to the style if `text` is non-`nil`. Otherwise,
+ it is ignored.
+ 
+ This attribute corresponds to the <a
+ href="https://www.mapbox.com/mapbox-gl-style-spec/#paint-text-translate"><code>text-translate</code></a>
+ layout property in the Mapbox Style Specification.
+ */
+@property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *textTranslation;
+#endif
 
 @property (nonatomic, null_resettable) MGLStyleValue<NSValue *> *textTranslate __attribute__((unavailable("Use textTranslation instead.")));
 
diff --git a/platform/darwin/src/NSValue+MGLStyleAttributeAdditions.mm b/platform/darwin/src/NSValue+MGLStyleAttributeAdditions.mm
index 59afe559d7..e66145aec1 100644
--- a/platform/darwin/src/NSValue+MGLStyleAttributeAdditions.mm
+++ b/platform/darwin/src/NSValue+MGLStyleAttributeAdditions.mm
@@ -12,6 +12,11 @@
 + (instancetype)mgl_valueWithOffsetArray:(std::array<float, 2>)offsetArray
 {
     CGVector vector = CGVectorMake(offsetArray[0], offsetArray[1]);
+#if !TARGET_OS_IPHONE
+    // Style specification assumes an origin at the upper-left corner.
+    // macOS defines an origin at the lower-left corner.
+    vector.dy *= -1;
+#endif
     return [NSValue value:&vector withObjCType:@encode(CGVector)];
 }
 
@@ -33,6 +38,9 @@
     NSAssert(strcmp(self.objCType, @encode(CGVector)) == 0, @"Value does not represent a CGVector");
     CGVector vector;
     [self getValue:&vector];
+#if !TARGET_OS_IPHONE
+    vector.dy *= -1;
+#endif
     return {
         static_cast<float>(vector.dx),
         static_cast<float>(vector.dy),
diff --git a/platform/macos/docs/guides/For Style Authors.md b/platform/macos/docs/guides/For Style Authors.md
index c58cb4badc..057534eef2 100644
--- a/platform/macos/docs/guides/For Style Authors.md
+++ b/platform/macos/docs/guides/For Style Authors.md
@@ -267,6 +267,12 @@ For padding attributes, note that the arguments to
 `EdgeInsets(top:left:bottom:right:)` in Swift are specified in counterclockwise
 order, in contrast to the clockwise order defined by the style specification.
 
+Additionally, on macOS, a screen coordinate of (0, 0) is located at the
+lower-left corner of the screen. Therefore, a positive `CGVector.dy` means an
+offset or translation upward, while a negative `CGVector.dy` means an offset or
+translation downward. This is the reverse of how `CGVector` is interpreted on
+iOS.
+
 ## Filtering sources
 
 You can filter a shape or vector source by setting the