From 962c51cf3e91e697bbe4d6d9958f742bb80aa006 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 17 Mar 2026 08:03:43 +0000
Subject: [PATCH 1/8] Initial plan


From 71c5b3f7ef9549dec8d2d5f9559c1c79c217bb45 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 17 Mar 2026 08:16:49 +0000
Subject: [PATCH 2/8] Update Figure.colorbar usage to use new
 label/unit/annot/tick/grid parameters

Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
---
 examples/gallery/3d_plots/3d_bar.py           |  5 ++++-
 examples/gallery/3d_plots/grdview_surface.py  |  2 +-
 examples/gallery/basemaps/ternary.py          |  2 +-
 examples/gallery/embellishments/colorbar.py   | 22 ++++++++++---------
 .../embellishments/colorbars_multiple.py      |  4 ++--
 examples/gallery/histograms/blockm.py         |  4 ++--
 examples/gallery/images/cross_section.py      |  5 +++--
 examples/gallery/images/grdclip.py            |  3 ++-
 examples/gallery/images/grdgradient.py        |  5 ++++-
 .../gallery/images/grdgradient_shading.py     |  4 +++-
 examples/gallery/maps/choropleth_map.py       |  2 +-
 examples/intro/02_contour_map.py              | 14 +++++-------
 .../advanced/3d_perspective_image.py          |  2 +-
 examples/tutorials/advanced/contour_map.py    |  2 +-
 .../advanced/draping_on_3d_surface.py         |  2 +-
 examples/tutorials/advanced/earth_relief.py   | 13 +++++------
 .../tutorials/advanced/focal_mechanisms.py    |  2 +-
 .../tutorials/advanced/working_with_panel.py  |  6 ++---
 examples/tutorials/basics/plot.py             |  2 +-
 19 files changed, 55 insertions(+), 46 deletions(-)

diff --git a/examples/gallery/3d_plots/3d_bar.py b/examples/gallery/3d_plots/3d_bar.py
index 70837d40894..d8554162f97 100644
--- a/examples/gallery/3d_plots/3d_bar.py
+++ b/examples/gallery/3d_plots/3d_bar.py
@@ -58,7 +58,10 @@
     perspective=True,
 )
 fig.colorbar(
-    frame=["xa1000f500+lElevation", "y+lm"],
+    annot=1000,
+    tick=500,
+    label="Elevation",
+    unit="m",
     position=Position("TR", cstype="inside", offset=1.4),
     orientation="vertical",
     length=7,
diff --git a/examples/gallery/3d_plots/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py
index 8c1814fc6eb..7279f5e02b0 100644
--- a/examples/gallery/3d_plots/grdview_surface.py
+++ b/examples/gallery/3d_plots/grdview_surface.py
@@ -57,6 +57,6 @@ def ackley(x, y):
 )
 
 # Add colorbar for gridded data in the Middle Right corner.
-fig.colorbar(frame="a2f1", position=Position("MR", cstype="outside"))
+fig.colorbar(annot=2, tick=1, position=Position("MR", cstype="outside"))
 
 fig.show()
diff --git a/examples/gallery/basemaps/ternary.py b/examples/gallery/basemaps/ternary.py
index 91da1586837..3900447cef7 100644
--- a/examples/gallery/basemaps/ternary.py
+++ b/examples/gallery/basemaps/ternary.py
@@ -43,6 +43,6 @@
 
 # Add a colorbar indicating the values given in the fourth column of the input dataset
 fig.colorbar(
-    position=Position("BC", cstype="outside", offset=(0, 1.5)), frame="x+lPermittivity"
+    position=Position("BC", cstype="outside", offset=(0, 1.5)), label="Permittivity"
 )
 fig.show()
diff --git a/examples/gallery/embellishments/colorbar.py b/examples/gallery/embellishments/colorbar.py
index 4e6c6be3701..5107bf2351a 100644
--- a/examples/gallery/embellishments/colorbar.py
+++ b/examples/gallery/embellishments/colorbar.py
@@ -4,11 +4,11 @@
 
 The :meth:`pygmt.Figure.colorbar` method creates a color scalebar. The colormap is set
 via the ``cmap`` parameter. A full list of available color palette tables can be found
-at :gmt-docs:`reference/cpts.html`. Use the ``frame`` parameter to add labels to the
-**x** and **y** axes of the colorbar by appending **+l** followed by the desired text.
-To add and adjust the annotations (**a**) and ticks (**f**) append the letter followed
-by the desired interval. The placement of the colorbar is set by passing a
-:class:`pygmt.params.Position` object to the ``position`` parameter.
+at :gmt-docs:`reference/cpts.html`. Use the ``label`` and ``unit`` parameters to add
+labels to the **x** and **y** axes of the colorbar, respectively. To set the annotation
+and tick intervals, use the ``annot`` and ``tick`` parameters. The placement of the
+colorbar is set by passing a :class:`pygmt.params.Position` object to the ``position``
+parameter.
 """
 
 # %%
@@ -21,9 +21,9 @@
 # ============
 # Create a colorbar designed for seismic tomography - roma
 # Colorbar is placed at Bottom Center (BC) by default if no position is given
-# Add quantity and unit as labels ("+l") to the x and y axes
-# Add annotations ("+a") in steps of 0.5 and ticks ("+f") in steps of 0.1
-fig.colorbar(cmap="SCM/roma", frame=["xa0.5f0.1+lVelocity", "y+lm/s"])
+# Add quantity and unit as labels to the x and y axes
+# Add annotations in steps of 0.5 and ticks in steps of 0.1
+fig.colorbar(cmap="SCM/roma", annot=0.5, tick=0.1, label="Velocity", unit="m/s")
 
 # ============
 # Create a colorbar showing the scientific rainbow - batlow
@@ -36,7 +36,8 @@
     width=0.5,
     orientation="horizontal",
     box=True,
-    frame=["x+lTemperature", "y+l°C"],
+    label="Temperature",
+    unit="°C",
     scale=100,
 )
 
@@ -53,7 +54,8 @@
     width=0.5,
     nan=True,
     label_as_column=True,
-    frame=["x+lElevation", "y+lm"],
+    label="Elevation",
+    unit="m",
     scale=10,
 )
 
diff --git a/examples/gallery/embellishments/colorbars_multiple.py b/examples/gallery/embellishments/colorbars_multiple.py
index 0edd822b8ce..913ff49ee21 100644
--- a/examples/gallery/embellishments/colorbars_multiple.py
+++ b/examples/gallery/embellishments/colorbars_multiple.py
@@ -29,7 +29,7 @@
         # "R?" means Winkel Tripel projection with map width automatically determined
         # from the subplot width.
         fig.grdimage(grid=grid_globe, projection="R?", region="g", frame="a")
-        fig.colorbar(frame=["a4000f2000", "x+lElevation", "y+lm"])
+        fig.colorbar(annot=4000, tick=2000, label="Elevation", unit="m")
     # Activate the second panel so that the colormap created by the makecpt function is
     # a panel-level CPT
     with fig.set_panel(panel=1):
@@ -37,6 +37,6 @@
         # "M?" means Mercator projection with map width also automatically determined
         # from the subplot width.
         fig.grdimage(grid=grid_subset, projection="M?", region=subset_region, frame="a")
-        fig.colorbar(frame=["a2000f1000", "x+lElevation", "y+lm"])
+        fig.colorbar(annot=2000, tick=1000, label="Elevation", unit="m")
 
 fig.show()
diff --git a/examples/gallery/histograms/blockm.py b/examples/gallery/histograms/blockm.py
index ba509d6dc0c..21ef080dffa 100644
--- a/examples/gallery/histograms/blockm.py
+++ b/examples/gallery/histograms/blockm.py
@@ -39,7 +39,7 @@
 fig.coast(land="darkgray", transparency=40)
 # Plot original data points
 fig.plot(x=data.longitude, y=data.latitude, style="c0.3c", fill="white", pen="1p,black")
-fig.colorbar(frame="x+lkm")
+fig.colorbar(label="km")
 
 fig.shift_origin(xshift="w+5c")
 
@@ -56,6 +56,6 @@
 )
 fig.coast(land="darkgray", transparency=40)
 fig.plot(x=data.longitude, y=data.latitude, style="c0.3c", fill="white", pen="1p,black")
-fig.colorbar(frame="x+lcount")
+fig.colorbar(label="count")
 
 fig.show()
diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py
index 019c69a1a9b..2def5f8759a 100644
--- a/examples/gallery/images/cross_section.py
+++ b/examples/gallery/images/cross_section.py
@@ -52,8 +52,9 @@
     # Add a box around the colobar, filled in white and a 30 % transparency, with a
     # 0.8-point thick, black, outline.
     box=Box(pen="0.8p,black", fill="white@30"),
-    # Add x- and y-labels ("+l")
-    frame=["x+lElevation", "y+lm"],
+    # Add label and unit for the colorbar
+    label="Elevation",
+    unit="m",
 )
 
 # Plot the survey line
diff --git a/examples/gallery/images/grdclip.py b/examples/gallery/images/grdclip.py
index 522e6e3dba0..17990e6f641 100644
--- a/examples/gallery/images/grdclip.py
+++ b/examples/gallery/images/grdclip.py
@@ -43,7 +43,8 @@
 )
 fig.grdimage(grid=grid)
 fig.colorbar(
-    frame=["x+lElevation", "y+lm"],
+    label="Elevation",
+    unit="m",
     position=Position("MR", cstype="outside", offset=(0.5, 0)),
     length=8,
 )
diff --git a/examples/gallery/images/grdgradient.py b/examples/gallery/images/grdgradient.py
index 8fd4976eeb6..86cf9fc8cf8 100644
--- a/examples/gallery/images/grdgradient.py
+++ b/examples/gallery/images/grdgradient.py
@@ -42,7 +42,10 @@
     position=Position("ML", cstype="outside", offset=(1.4, 0)),
     length=7,
     width=0.5,
-    frame=["xa1000f500+lElevation", "y+lm"],
+    annot=1000,
+    tick=500,
+    label="Elevation",
+    unit="m",
 )
 
 # --------------- plotting the hillshade map -----------
diff --git a/examples/gallery/images/grdgradient_shading.py b/examples/gallery/images/grdgradient_shading.py
index a2fc6978433..f040c19b49e 100644
--- a/examples/gallery/images/grdgradient_shading.py
+++ b/examples/gallery/images/grdgradient_shading.py
@@ -71,7 +71,9 @@
     length=14,
     width=0.4,
     orientation="horizontal",
-    frame="xa2000f500+lElevation (m)",
+    annot=2000,
+    tick=500,
+    label="Elevation (m)",
 )
 
 fig.show()
diff --git a/examples/gallery/maps/choropleth_map.py b/examples/gallery/maps/choropleth_map.py
index 0a43f0629ea..3b22806855b 100644
--- a/examples/gallery/maps/choropleth_map.py
+++ b/examples/gallery/maps/choropleth_map.py
@@ -38,7 +38,7 @@
 
 # Add colorbar legend.
 fig.colorbar(
-    frame="x+lPopulation (millions)",
+    label="Population (millions)",
     position=Position("ML", offset=(2, -2.5)),
     length=5,
     fg_triangle=True,
diff --git a/examples/intro/02_contour_map.py b/examples/intro/02_contour_map.py
index 3868f1a45fd..2294d848326 100644
--- a/examples/intro/02_contour_map.py
+++ b/examples/intro/02_contour_map.py
@@ -54,18 +54,16 @@
 # To show how the plotted colors relate to the Earth relief, a colorbar can be added
 # using the :meth:`pygmt.Figure.colorbar` method.
 #
-# To control the annotation and labels on the colorbar, a list is passed to the
-# ``frame`` parameter. The value beginning with ``"a"`` sets the interval for the
-# annotation on the colorbar, in this case every 1,000 meters. To set the label for an
-# axis on the colorbar, the argument begins with either ``"x+l"`` (x-axis) or ``"y+l"``
-# (y-axis), followed by the intended label.
+# To control the annotation and labels on the colorbar, use the ``annot`` parameter to
+# set the annotation interval (in this case every 1,000 meters), the ``label`` parameter
+# to set the x-axis label, and the ``unit`` parameter to set the y-axis label.
 #
 # By default, the CPT for the colorbar is the same as the one set in
 # :meth:`pygmt.Figure.grdimage`.
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="SCM/oleron")
-fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
+fig.colorbar(annot=1000, label="Elevation", unit="m")
 fig.show()
 
 
@@ -87,7 +85,7 @@
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="SCM/oleron")
 fig.grdcontour(grid=grid, levels=500, annotation=1000)
-fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
+fig.colorbar(annot=1000, label="Elevation", unit="m")
 fig.show()
 
 
@@ -103,7 +101,7 @@
 fig.grdimage(grid=grid, frame="a", projection="M10c", cmap="SCM/oleron")
 fig.grdcontour(grid=grid, levels=500, annotation=1000)
 fig.coast(shorelines="2p", land="lightgray")
-fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
+fig.colorbar(annot=1000, label="Elevation", unit="m")
 fig.show()
 
 
diff --git a/examples/tutorials/advanced/3d_perspective_image.py b/examples/tutorials/advanced/3d_perspective_image.py
index 1f83def5499..aec98b5b9fe 100644
--- a/examples/tutorials/advanced/3d_perspective_image.py
+++ b/examples/tutorials/advanced/3d_perspective_image.py
@@ -93,7 +93,7 @@
     # Set the contour pen thickness to 0.1 points
     contour_pen="0.1p",
 )
-fig.colorbar(perspective=True, frame=["a500", "x+lElevation", "y+lm"])
+fig.colorbar(perspective=True, annot=500, label="Elevation", unit="m")
 fig.show()
 
 # sphinx_gallery_thumbnail_number = 4
diff --git a/examples/tutorials/advanced/contour_map.py b/examples/tutorials/advanced/contour_map.py
index f36739822ef..2ac5d558d50 100644
--- a/examples/tutorials/advanced/contour_map.py
+++ b/examples/tutorials/advanced/contour_map.py
@@ -86,7 +86,7 @@
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, cmap="gmt/haxby", projection="M10c", frame=True)
 fig.grdcontour(grid=grid, annotation=1000, levels=250, limit=[-4000, -2000])
-fig.colorbar(frame=["x+lelevation", "y+lm"])
+fig.colorbar(label="elevation", unit="m")
 fig.show()
 
 # sphinx_gallery_thumbnail_number = 5
diff --git a/examples/tutorials/advanced/draping_on_3d_surface.py b/examples/tutorials/advanced/draping_on_3d_surface.py
index f0c83765638..a5998f477f4 100644
--- a/examples/tutorials/advanced/draping_on_3d_surface.py
+++ b/examples/tutorials/advanced/draping_on_3d_surface.py
@@ -69,7 +69,7 @@
 )
 
 # Add colorbar for the crustal age
-fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], nan=True)
+fig.colorbar(label="seafloor crustal age", unit="Myr", nan=True)
 
 fig.show()
 
diff --git a/examples/tutorials/advanced/earth_relief.py b/examples/tutorials/advanced/earth_relief.py
index 4038eb6ebb9..b6f9f5a22d5 100644
--- a/examples/tutorials/advanced/earth_relief.py
+++ b/examples/tutorials/advanced/earth_relief.py
@@ -69,15 +69,14 @@
 #
 # The :meth:`pygmt.Figure.colorbar` method displays the CPT and the associated z-values
 # of the figure, and by default uses the same CPT set by the ``cmap`` parameter for
-# :meth:`pygmt.Figure.grdimage`. The ``frame`` parameter for
-# :meth:`pygmt.Figure.colorbar` can be used to set the axis intervals and labels. A list
-# is used to pass multiple arguments to ``frame``. In the example below, ``"a2500"``
-# sets the axis interval to 2,500, ``"x+lElevation"`` sets the x-axis label, and
-# ``"y+lm"`` sets the y-axis label.
+# :meth:`pygmt.Figure.grdimage`. The ``annot`` parameter sets the annotation interval,
+# the ``label`` parameter sets the x-axis label, and the ``unit`` parameter sets the
+# y-axis label. In the example below, ``annot=2500`` sets the axis interval to 2,500,
+# ``label="Elevation"`` sets the x-axis label, and ``unit="m"`` sets the y-axis label.
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, projection="R12c", cmap="gmt/geo")
-fig.colorbar(frame=["a2500", "x+lElevation", "y+lm"])
+fig.colorbar(annot=2500, label="Elevation", unit="m")
 fig.show()
 
 
@@ -97,7 +96,7 @@
 grid = pygmt.datasets.load_earth_relief(resolution="10m", region=[-14, 30, 35, 60])
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, projection="M15c", frame="a", cmap="gmt/geo")
-fig.colorbar(frame=["a1000", "x+lElevation", "y+lm"])
+fig.colorbar(annot=1000, label="Elevation", unit="m")
 fig.show()
 
 # sphinx_gallery_thumbnail_number = 5
diff --git a/examples/tutorials/advanced/focal_mechanisms.py b/examples/tutorials/advanced/focal_mechanisms.py
index d4f76e49d7d..d24c4407236 100644
--- a/examples/tutorials/advanced/focal_mechanisms.py
+++ b/examples/tutorials/advanced/focal_mechanisms.py
@@ -309,7 +309,7 @@
 
 # Set up colormap and colorbar for hypocentral depth
 pygmt.makecpt(cmap="SCM/lajolla", series=[0, 20])
-fig.colorbar(frame=["x+lhypocentral depth", "y+lkm"])
+fig.colorbar(label="hypocentral depth", unit="km")
 
 fig.meca(
     spec=aki_multiple,
diff --git a/examples/tutorials/advanced/working_with_panel.py b/examples/tutorials/advanced/working_with_panel.py
index e9365489a94..3b4e2ad1132 100644
--- a/examples/tutorials/advanced/working_with_panel.py
+++ b/examples/tutorials/advanced/working_with_panel.py
@@ -136,9 +136,9 @@ def view(central_lon):
         frame="g30",
     )
     # Add a horizontal colorbar for the elevation
-    # with annotations (a) in steps of 2000 and ticks (f) in steps of 1000
-    # and labels (+l) at the x-axis "Elevation" and y-axis "m" (meters)
-    fig.colorbar(frame=["a2000f1000", "x+lElevation", "y+lm"])
+    # with annotations in steps of 2000 and ticks in steps of 1000
+    # and labels for the x-axis "Elevation" and y-axis "m" (meters)
+    fig.colorbar(annot=2000, tick=1000, label="Elevation", unit="m")
     return fig
 
 
diff --git a/examples/tutorials/basics/plot.py b/examples/tutorials/basics/plot.py
index e402376eb71..5ffdc024387 100644
--- a/examples/tutorials/basics/plot.py
+++ b/examples/tutorials/basics/plot.py
@@ -108,7 +108,7 @@
     style="cc",
     pen="black",
 )
-fig.colorbar(frame="xaf+lDepth (km)")
+fig.colorbar(annot=True, tick=True, label="Depth (km)")
 fig.legend(
     spec=legend,
     position=Position("BR", offset=0.2),

From 4c9193724583576dbd09df822bb40422ccc0d133 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Tue, 17 Mar 2026 16:32:29 +0800
Subject: [PATCH 3/8] Update examples/tutorials/advanced/earth_relief.py

---
 examples/tutorials/advanced/earth_relief.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/examples/tutorials/advanced/earth_relief.py b/examples/tutorials/advanced/earth_relief.py
index b6f9f5a22d5..1651a185d57 100644
--- a/examples/tutorials/advanced/earth_relief.py
+++ b/examples/tutorials/advanced/earth_relief.py
@@ -71,8 +71,7 @@
 # of the figure, and by default uses the same CPT set by the ``cmap`` parameter for
 # :meth:`pygmt.Figure.grdimage`. The ``annot`` parameter sets the annotation interval,
 # the ``label`` parameter sets the x-axis label, and the ``unit`` parameter sets the
-# y-axis label. In the example below, ``annot=2500`` sets the axis interval to 2,500,
-# ``label="Elevation"`` sets the x-axis label, and ``unit="m"`` sets the y-axis label.
+# y-axis label.
 
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, projection="R12c", cmap="gmt/geo")

From 4d4119b5e9031384183c2e050df43f4ca83c102a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 17 Mar 2026 08:59:56 +0000
Subject: [PATCH 4/8] Fix frame=True in colorbar._build_frame to be equivalent
 to annot=True, tick=True

Co-authored-by: seisman <3974108+seisman@users.noreply.github.com>
---
 pygmt/src/colorbar.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/pygmt/src/colorbar.py b/pygmt/src/colorbar.py
index 89a3e2d0d40..b73440623d1 100644
--- a/pygmt/src/colorbar.py
+++ b/pygmt/src/colorbar.py
@@ -50,11 +50,18 @@ def _build_frame(
 
     >>> _build_frame(frame="none")
     'none'
+    >>> list(_build_frame(frame=True))  # frame=True is equivalent to annot=True, tick=True
+    ['xaf']
     >>> _build_frame()  # Passing no parameters returns None
     """
     # Using the old 'frame' parameter.
     if frame is not None and frame is not False:
-        return frame
+        if frame is True:
+            # frame=True is equivalent to annot=True, tick=True
+            annot = True
+            tick = True
+        else:
+            return frame
 
     _xaxis_is_set = any(
         v is not None and v is not False

From 268a04eb156f0f21db8d5381eede6dfa570e04f2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 17 Mar 2026 09:04:01 +0000
Subject: [PATCH 5/8] Revert "Fix frame=True in colorbar._build_frame to be
 equivalent to annot=True, tick=True"

This reverts commit 4d4119b5e9031384183c2e050df43f4ca83c102a.
---
 pygmt/src/colorbar.py | 9 +--------
 1 file changed, 1 insertion(+), 8 deletions(-)

diff --git a/pygmt/src/colorbar.py b/pygmt/src/colorbar.py
index b73440623d1..89a3e2d0d40 100644
--- a/pygmt/src/colorbar.py
+++ b/pygmt/src/colorbar.py
@@ -50,18 +50,11 @@ def _build_frame(
 
     >>> _build_frame(frame="none")
     'none'
-    >>> list(_build_frame(frame=True))  # frame=True is equivalent to annot=True, tick=True
-    ['xaf']
     >>> _build_frame()  # Passing no parameters returns None
     """
     # Using the old 'frame' parameter.
     if frame is not None and frame is not False:
-        if frame is True:
-            # frame=True is equivalent to annot=True, tick=True
-            annot = True
-            tick = True
-        else:
-            return frame
+        return frame
 
     _xaxis_is_set = any(
         v is not None and v is not False

From ccd21bd220b49cf78550ceff5e3b7867c22b5f31 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Tue, 17 Mar 2026 17:32:58 +0800
Subject: [PATCH 6/8] Cleanup docstrings

---
 examples/gallery/embellishments/colorbar.py   | 21 ++++++++-----------
 examples/gallery/images/cross_section.py      |  6 +-----
 examples/intro/02_contour_map.py              |  5 +++--
 .../tutorials/advanced/working_with_panel.py  |  4 +---
 4 files changed, 14 insertions(+), 22 deletions(-)

diff --git a/examples/gallery/embellishments/colorbar.py b/examples/gallery/embellishments/colorbar.py
index 5107bf2351a..7d71a77789a 100644
--- a/examples/gallery/embellishments/colorbar.py
+++ b/examples/gallery/embellishments/colorbar.py
@@ -4,11 +4,11 @@
 
 The :meth:`pygmt.Figure.colorbar` method creates a color scalebar. The colormap is set
 via the ``cmap`` parameter. A full list of available color palette tables can be found
-at :gmt-docs:`reference/cpts.html`. Use the ``label`` and ``unit`` parameters to add
-labels to the **x** and **y** axes of the colorbar, respectively. To set the annotation
-and tick intervals, use the ``annot`` and ``tick`` parameters. The placement of the
-colorbar is set by passing a :class:`pygmt.params.Position` object to the ``position``
-parameter.
+at :gmt-docs:`reference/cpts.html`. Use the ``label`` and ``unit`` parameters to set the
+labels for the long- and short-dimensions of the colorbar, respectively. To set the
+annotation and tick intervals, use the ``annot`` and ``tick`` parameters. The placement
+of the colorbar is set by passing a :class:`pygmt.params.Position` object to the
+``position`` parameter.
 """
 
 # %%
@@ -21,16 +21,13 @@
 # ============
 # Create a colorbar designed for seismic tomography - roma
 # Colorbar is placed at Bottom Center (BC) by default if no position is given
-# Add quantity and unit as labels to the x and y axes
-# Add annotations in steps of 0.5 and ticks in steps of 0.1
 fig.colorbar(cmap="SCM/roma", annot=0.5, tick=0.1, label="Velocity", unit="m/s")
 
 # ============
 # Create a colorbar showing the scientific rainbow - batlow
 fig.colorbar(
     cmap="SCM/batlow",
-    # A horizontal colorbar positioned at map coordinates (0.3, 8.7), with a
-    # length of 4 cm and a width of 0.5 cm.
+    # A horizontal colorbar positioned at map coordinates (0.3, 8.7).
     position=Position((0.3, 8.7), cstype="mapcoords"),
     length=4,
     width=0.5,
@@ -46,9 +43,9 @@
 fig.colorbar(
     cmap="SCM/oleron",
     # Colorbar placed at Middle Right (MR) outside the plot bounding box, offset by 1 cm
-    # horizontally and 0 cm vertically from anchor point, with a length of 7 cm and
-    # width of 0.5 cm, and a rectangle for NaN values.
-    # Note that the label 'Elevation' is plotted vertically as a column of characters.
+    # horizontally and 0 cm vertically from anchor point, with a rectangle for NaN
+    # values. Note that the label 'Elevation' is plotted vertically as a column of
+    # characters.
     position=Position("MR", cstype="outside", offset=(1, 0)),
     length=7,
     width=0.5,
diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py
index 2def5f8759a..0126a3ac793 100644
--- a/examples/gallery/images/cross_section.py
+++ b/examples/gallery/images/cross_section.py
@@ -43,16 +43,12 @@
 fig.colorbar(
     # Place the colorbar inside the plot in the Bottom Right (BR) corner with an offset
     # of 0.7 centimeters and 0.3 centimeters in x- or y-directions, respectively;
-    # move the x-label above the horizontal colorbar.
     position=Position("BR", offset=(0.7, 0.8)),
     length=5,
     width=0.3,
     orientation="horizontal",
-    move_text="label",
-    # Add a box around the colobar, filled in white and a 30 % transparency, with a
-    # 0.8-point thick, black, outline.
+    move_text="label",  # move the x-label above the horizontal colorbar.
     box=Box(pen="0.8p,black", fill="white@30"),
-    # Add label and unit for the colorbar
     label="Elevation",
     unit="m",
 )
diff --git a/examples/intro/02_contour_map.py b/examples/intro/02_contour_map.py
index 2294d848326..80749847cd2 100644
--- a/examples/intro/02_contour_map.py
+++ b/examples/intro/02_contour_map.py
@@ -55,8 +55,9 @@
 # using the :meth:`pygmt.Figure.colorbar` method.
 #
 # To control the annotation and labels on the colorbar, use the ``annot`` parameter to
-# set the annotation interval (in this case every 1,000 meters), the ``label`` parameter
-# to set the x-axis label, and the ``unit`` parameter to set the y-axis label.
+# set the annotation interval (in this case every 1,000 meters), the ``label`` and
+# ``unit``parameters to set the labels for the long- and short-dimensions of the
+# colorbar, respectively.
 #
 # By default, the CPT for the colorbar is the same as the one set in
 # :meth:`pygmt.Figure.grdimage`.
diff --git a/examples/tutorials/advanced/working_with_panel.py b/examples/tutorials/advanced/working_with_panel.py
index 3b4e2ad1132..55271254cd8 100644
--- a/examples/tutorials/advanced/working_with_panel.py
+++ b/examples/tutorials/advanced/working_with_panel.py
@@ -135,9 +135,7 @@ def view(central_lon):
         cmap=True,  # Use colormap defined above
         frame="g30",
     )
-    # Add a horizontal colorbar for the elevation
-    # with annotations in steps of 2000 and ticks in steps of 1000
-    # and labels for the x-axis "Elevation" and y-axis "m" (meters)
+    # Add a horizontal colorbar for the elevation.
     fig.colorbar(annot=2000, tick=1000, label="Elevation", unit="m")
     return fig
 

From e22a64a2c738bc6f395c60a0adcfa0ba6268e060 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Tue, 17 Mar 2026 17:36:33 +0800
Subject: [PATCH 7/8] Improve the docstrings

---
 examples/gallery/embellishments/colorbar.py | 2 +-
 examples/intro/02_contour_map.py            | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/gallery/embellishments/colorbar.py b/examples/gallery/embellishments/colorbar.py
index 7d71a77789a..7beda96c5e3 100644
--- a/examples/gallery/embellishments/colorbar.py
+++ b/examples/gallery/embellishments/colorbar.py
@@ -5,7 +5,7 @@
 The :meth:`pygmt.Figure.colorbar` method creates a color scalebar. The colormap is set
 via the ``cmap`` parameter. A full list of available color palette tables can be found
 at :gmt-docs:`reference/cpts.html`. Use the ``label`` and ``unit`` parameters to set the
-labels for the long- and short-dimensions of the colorbar, respectively. To set the
+labels along the long and short dimensions of the colorbar, respectively. To set the
 annotation and tick intervals, use the ``annot`` and ``tick`` parameters. The placement
 of the colorbar is set by passing a :class:`pygmt.params.Position` object to the
 ``position`` parameter.
diff --git a/examples/intro/02_contour_map.py b/examples/intro/02_contour_map.py
index 80749847cd2..0adc63cf6b5 100644
--- a/examples/intro/02_contour_map.py
+++ b/examples/intro/02_contour_map.py
@@ -56,7 +56,7 @@
 #
 # To control the annotation and labels on the colorbar, use the ``annot`` parameter to
 # set the annotation interval (in this case every 1,000 meters), the ``label`` and
-# ``unit``parameters to set the labels for the long- and short-dimensions of the
+# ``unit``parameters to set the labels along the long and short dimensions of the
 # colorbar, respectively.
 #
 # By default, the CPT for the colorbar is the same as the one set in

From 777938aa6ea48e4758777b6773686c22829d899f Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 19 Mar 2026 05:36:35 +0800
Subject: [PATCH 8/8] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
---
 examples/gallery/histograms/blockm.py                | 2 +-
 examples/gallery/images/cross_section.py             | 2 +-
 examples/tutorials/advanced/contour_map.py           | 2 +-
 examples/tutorials/advanced/draping_on_3d_surface.py | 2 +-
 examples/tutorials/advanced/focal_mechanisms.py      | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/examples/gallery/histograms/blockm.py b/examples/gallery/histograms/blockm.py
index 21ef080dffa..73bce35d0ac 100644
--- a/examples/gallery/histograms/blockm.py
+++ b/examples/gallery/histograms/blockm.py
@@ -56,6 +56,6 @@
 )
 fig.coast(land="darkgray", transparency=40)
 fig.plot(x=data.longitude, y=data.latitude, style="c0.3c", fill="white", pen="1p,black")
-fig.colorbar(label="count")
+fig.colorbar(label="Count")
 
 fig.show()
diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py
index 0126a3ac793..10033b615c8 100644
--- a/examples/gallery/images/cross_section.py
+++ b/examples/gallery/images/cross_section.py
@@ -42,7 +42,7 @@
 # Add a colorbar for the elevation
 fig.colorbar(
     # Place the colorbar inside the plot in the Bottom Right (BR) corner with an offset
-    # of 0.7 centimeters and 0.3 centimeters in x- or y-directions, respectively;
+    # of 0.7 centimeters and 0.3 centimeters in x- or y-directions, respectively.
     position=Position("BR", offset=(0.7, 0.8)),
     length=5,
     width=0.3,
diff --git a/examples/tutorials/advanced/contour_map.py b/examples/tutorials/advanced/contour_map.py
index 2ac5d558d50..76b8f515454 100644
--- a/examples/tutorials/advanced/contour_map.py
+++ b/examples/tutorials/advanced/contour_map.py
@@ -86,7 +86,7 @@
 fig = pygmt.Figure()
 fig.grdimage(grid=grid, cmap="gmt/haxby", projection="M10c", frame=True)
 fig.grdcontour(grid=grid, annotation=1000, levels=250, limit=[-4000, -2000])
-fig.colorbar(label="elevation", unit="m")
+fig.colorbar(label="Elevation", unit="m")
 fig.show()
 
 # sphinx_gallery_thumbnail_number = 5
diff --git a/examples/tutorials/advanced/draping_on_3d_surface.py b/examples/tutorials/advanced/draping_on_3d_surface.py
index a5998f477f4..8a35d2797a3 100644
--- a/examples/tutorials/advanced/draping_on_3d_surface.py
+++ b/examples/tutorials/advanced/draping_on_3d_surface.py
@@ -69,7 +69,7 @@
 )
 
 # Add colorbar for the crustal age
-fig.colorbar(label="seafloor crustal age", unit="Myr", nan=True)
+fig.colorbar(label="Seafloor crustal age", unit="Myr", nan=True)
 
 fig.show()
 
diff --git a/examples/tutorials/advanced/focal_mechanisms.py b/examples/tutorials/advanced/focal_mechanisms.py
index d24c4407236..abd6a090c35 100644
--- a/examples/tutorials/advanced/focal_mechanisms.py
+++ b/examples/tutorials/advanced/focal_mechanisms.py
@@ -309,7 +309,7 @@
 
 # Set up colormap and colorbar for hypocentral depth
 pygmt.makecpt(cmap="SCM/lajolla", series=[0, 20])
-fig.colorbar(label="hypocentral depth", unit="km")
+fig.colorbar(label="Hypocentral depth", unit="km")
 
 fig.meca(
     spec=aki_multiple,