diff --git a/src/components/shapes/attributes.js b/src/components/shapes/attributes.js
index eed805b2928..71a5475aee0 100644
--- a/src/components/shapes/attributes.js
+++ b/src/components/shapes/attributes.js
@@ -176,8 +176,9 @@ module.exports = templatedArray('shape', {
         max: 1,
         editType: 'calc',
         description: [
-            'Only relevant if `xref` is a (multi-)category axes. Shifts `x0` by a fraction of the',
-            'reference unit. E.g. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.'
+            'Shifts `x0` away from the center of the category when `xref` is a *category* or',
+            '*multicategory* axis. -0.5 corresponds to the start of the category and 0.5',
+            'corresponds to the end of the category.'
         ].join(' ')
     },
     x1shift: {
@@ -187,8 +188,9 @@ module.exports = templatedArray('shape', {
         max: 1,
         editType: 'calc',
         description: [
-            'Only relevant if `xref` is a (multi-)category axes. Shifts `x1` by a fraction of the',
-            'reference unit. E.g. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.'
+            'Shifts `x1` away from the center of the category when `xref` is a *category* or',
+            '*multicategory* axis. -0.5 corresponds to the start of the category and 0.5',
+            'corresponds to the end of the category.'
         ].join(' ')
     },
     yref: extendFlat({}, annAttrs.yref, {
@@ -248,8 +250,9 @@ module.exports = templatedArray('shape', {
         max: 1,
         editType: 'calc',
         description: [
-            'Only relevant if `yref` is a (multi-)category axes. Shifts `y0` by a fraction of the',
-            'reference unit. E.g. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.'
+            'Shifts `y0` away from the center of the category when `yref` is a *category* or',
+            '*multicategory* axis. -0.5 corresponds to the start of the category and 0.5',
+            'corresponds to the end of the category.'
         ].join(' ')
     },
     y1shift: {
@@ -259,8 +262,9 @@ module.exports = templatedArray('shape', {
         max: 1,
         editType: 'calc',
         description: [
-            'Only relevant if `yref` is a (multi-)category axes. Shifts `y1` by a fraction of the',
-            'reference unit. E.g. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.'
+            'Shifts `y1` away from the center of the category when `yref` is a *category* or',
+            '*multicategory* axis. -0.5 corresponds to the start of the category and 0.5',
+            'corresponds to the end of the category.'
         ].join(' ')
     },
     path: {
diff --git a/test/plot-schema.json b/test/plot-schema.json
index 584bdd8680a..a105ef852ba 100644
--- a/test/plot-schema.json
+++ b/test/plot-schema.json
@@ -10006,7 +10006,7 @@
        "valType": "any"
       },
       "x0shift": {
-       "description": "Only relevant if `xref` is a (multi-)category axes. Shifts `x0` by a fraction of the reference unit. E.g. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.",
+       "description": "Shifts `x0` away from the center of the category when `xref` is a *category* or *multicategory* axis. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.",
        "dflt": 0,
        "editType": "calc",
        "max": 1,
@@ -10019,7 +10019,7 @@
        "valType": "any"
       },
       "x1shift": {
-       "description": "Only relevant if `xref` is a (multi-)category axes. Shifts `x1` by a fraction of the reference unit. E.g. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.",
+       "description": "Shifts `x1` away from the center of the category when `xref` is a *category* or *multicategory* axis. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.",
        "dflt": 0,
        "editType": "calc",
        "max": 1,
@@ -10056,7 +10056,7 @@
        "valType": "any"
       },
       "y0shift": {
-       "description": "Only relevant if `yref` is a (multi-)category axes. Shifts `y0` by a fraction of the reference unit. E.g. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.",
+       "description": "Shifts `y0` away from the center of the category when `yref` is a *category* or *multicategory* axis. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.",
        "dflt": 0,
        "editType": "calc",
        "max": 1,
@@ -10069,7 +10069,7 @@
        "valType": "any"
       },
       "y1shift": {
-       "description": "Only relevant if `yref` is a (multi-)category axes. Shifts `y1` by a fraction of the reference unit. E.g. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.",
+       "description": "Shifts `y1` away from the center of the category when `yref` is a *category* or *multicategory* axis. -0.5 corresponds to the start of the category and 0.5 corresponds to the end of the category.",
        "dflt": 0,
        "editType": "calc",
        "max": 1,