diff --git a/doc/python/builtin-colorscales.md b/doc/python/builtin-colorscales.md
index 0363100c401..7f6e674e22c 100644
--- a/doc/python/builtin-colorscales.md
+++ b/doc/python/builtin-colorscales.md
@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
+      format_version: "1.2"
       jupytext_version: 1.3.1
   kernelspec:
     display_name: Python 3
@@ -22,34 +22,39 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.6.8
   plotly:
-    description: A reference for the built-in named continuous (sequential, diverging
-      and cylclical) colorscales in Plotly.
+    description:
+      A reference for the built-in named continuous (sequential, diverging
+      and cylclical) color scales in Plotly.
     display_as: file_settings
     has_thumbnail: true
     ipynb: ~notebook_demo/187
     language: python
     layout: base
-    name: Built-in Continuous Colorscales
+    name: Built-in Continuous Color Scales
     order: 27
     permalink: python/builtin-colorscales/
     thumbnail: thumbnail/heatmap_colorscale.jpg
     v4upgrade: true
 ---
 
-### Using Built-In Colorscales
+### Using Built-In Continuous Color Scales
 
 Many Plotly Express functions accept a `color_continuous_scale` argument and many trace
 types have a `colorscale` attribute in their schema. Plotly comes with a large number of
-built-in continuous colorscales, which can be referred to in Python code when setting the above arguments,
+built-in continuous color scales, which can be referred to in Python code when setting the above arguments,
 either by name in a case-insensitive string e.g. `px.scatter(continuous_color_scale="Viridis"`) or by reference e.g.
 `go.Scatter(marker_colorscale=plotly.colors.sequential.Viridis)`. They can also be reversed by adding `_r` at the end
 e.g. `"Viridis_r"` or `plotly.colors.sequential.Viridis_r`.
 
 The `plotly.colours` module is also available under `plotly.express.colors` so you can refer to it as `px.colors`.
 
-When using continuous colorscales, you will often want to [configure various aspects of its range and colorbar](/python/colorscales/).
+When using continuous color scales, you will often want to [configure various aspects of its range and colorbar](/python/colorscales/).
 
-### Named Built-In Colorscales
+### Discrete Color Sequences
+
+Plotly also comes with some built-in [discrete color sequences](/python/discrete-color/) which are _not intended_ to be used with the `color_continuous_scale` argument as they are not designed for interpolation to occur between adjacent colors.
+
+### Named Built-In Continuous Color Scales
 
 You can use any of the following names as string values to set `continuous_color_scale` or `colorscale` arguments.
 These strings are case-insensitive and you can append `_r` to them to reverse the order of the scale.
@@ -62,7 +67,15 @@ named_colorscales = px.colors.named_colorscales()
 print("\n".join(wrap("".join('{:<12}'.format(c) for c in named_colorscales), 96)))
 ```
 
-### Built-In Sequential Colorscales
+Built-in color scales are stored as lists of CSS colors:
+
+```python
+import plotly.express as px
+
+print(px.colors.sequential.Plasma)
+```
+
+### Built-In Sequential Color scales
 
 A collection of predefined sequential colorscales is provided in the `plotly.colors.sequential` module. Sequential color scales are appropriate for most continuous data, but in some cases it can be helpful to use a diverging or cyclical color scale (see below).
 
@@ -78,9 +91,9 @@ fig.show()
 Note: `RdBu` was included in this module by mistake, even though it is a diverging color scale.
 It is intentionally left in for backwards-compatibility reasons.
 
-### Built-In Diverging Colorscales
+### Built-In Diverging Color scales
 
-A collection of predefined diverging colorscales is provided in the `plotly.colors.diverging` module.
+A collection of predefined diverging color scales is provided in the `plotly.colors.diverging` module.
 Diverging color scales are appropriate for continuous data that has a natural midpoint
 other otherwise informative special value, such as 0 altitude, or the boiling point
 of a liquid. These scales are intended to be used when [explicitly setting the midpoint of the scale](/python/colorscales/#setting-the-midpoint-of-a-diverging-colorscale).
@@ -94,9 +107,9 @@ fig = px.colors.diverging.swatches()
 fig.show()
 ```
 
-### Built-In Cyclical Colorscales
+### Built-In Cyclical Color scales
 
-A collection of predefined cyclical colorscales is provided in the `plotly.colors.cyclical` module.
+A collection of predefined cyclical color scales is provided in the `plotly.colors.cyclical` module.
 Cyclical color scales are appropriate for continuous data that has a natural cyclical
 structure, such as temporal data (hour of day, day of week, day of year, seasons) or
 complex numbers or other phase or angular data.
diff --git a/doc/python/colorscales.md b/doc/python/colorscales.md
index b51081bd5cf..918c308557c 100644
--- a/doc/python/colorscales.md
+++ b/doc/python/colorscales.md
@@ -23,14 +23,14 @@ jupyter:
     version: 3.6.8
   plotly:
     description:
-      How to set colorscales and heatmap colorscales in Python and Plotly.
-      Divergent, sequential, and qualitative colorscales.
+      How to set, create and control continous color scales and color bars
+      in scatter, bar, map and heatmap figures.
     display_as: file_settings
     has_thumbnail: true
     ipynb: ~notebook_demo/187
     language: python
     layout: base
-    name: Colorscales
+    name: Continuous Color Scales and Color Bars
     order: 20
     permalink: python/colorscales/
     redirect_from: python/logarithmic-color-scale/
@@ -38,13 +38,64 @@ jupyter:
     v4upgrade: true
 ---
 
-### Built-In Colorscales
+### Continuous vs Discrete Color
 
-Plotly comes with a large number of [Built-in Continuous Colorscales](/python/builtin-colorscales/).
+In the same way as the X or Y position of a mark in cartesian coordinates can be used to represent continuous values (i.e. amounts or moments in time) or categories (i.e. labels), color can be used to represent continuous or categorical data. This page is about using color to represent **continuous** data, but Plotly can also [represent categorical values with color](/python/discrete-color/).
 
-### Using Built-In Colorscales in Plotly Express
+### Continuous Color Concepts
 
-Here is an example that creates a scatter plot using Plotly Express, with points colored using the Viridis colorscale.
+This document explains the following four continuous-color-related concepts:
+
+- **color scales** represent a mapping between the range 0 to 1 and some color domain within which colors are to be interpolated (unlike [discrete color sequences](/python/discrete-color/) which are never interpolated). Color scale defaults depend on the `layout.colorscales` attributes of the active [template](/python/templates/), and can be explicitly specified using the `color_continuous_scale` argument for many [Plotly Express](/python/plotly-express/) functions or the `colorscale` argument in various `graph_objects` such as `layout.coloraxis` or `marker.colorscale` in `go.Scatter` traces or `colorscale` in `go.Heatmap` traces. For example `[(0,"blue"), (1,"red")]` is a simple color scale that interpolated between blue and red via purple, which can also be implicitly represented as `["blue", "red"]` and happens to be one of the [built-in color scales](/python/builtin-colorscales) and therefore referred to as `"bluered"` or `plotly.colors.sequential.Bluered`.
+- **color ranges** represent the minimum to maximum range of data to be mapped onto the 0 to 1 input range of the color scale. Color ranges default to the range of the input data and can be explicitly specified using either the `range_color` or `color_continous_midpoint` arguments for many Plotly Express functions, or `cmin`/`cmid`/`cmax` or `zmin`/`zmid`/`zmax` for various `graph_objects` such as `layout.coloraxis.cmin` or `marker.cmin` in `go.Scatter` traces or `cmin` in `go.Heatmap` traces. For example, if a color range of `[100, 200]` is used with the color scale above, then any mark with a color value of 100 or less will be blue, and 200 or more will be red. Marks with values in between will be various shades of purple.
+- **color bars** are legend-like visible representations of the color range and color scale with optional tick labels and tick marks. Color bars can be configured with attributes inside `layout.coloraxis.colorbar` or in places like `marker.colorbar` in `go.Scatter` traces or `colorbar` in `go.Heatmap` traces.
+- **color axes** connect color scales, color ranges and color bars to a trace's data. By default, any colorable attribute in a trace is attached to its own local color axis, but color axes may also be shared across attributes and traces by setting e.g. `marker.coloraxis` in `go.Scatter` traces or `coloraxis` in `go.Heatmap` traces. Local color axis attributes are configured within traces e.g. `marker.showscale` whereas shared color axis attributes are configured within the Layout e.g. `layout.coloraxis.showscale`.
+
+### Continuous Color with Plotly Express
+
+Most Plotly Express functions accept a `color` argument which automatically assigns data values to continuous color **if the data is numeric**. If the data contains strings, the color will automatically be considered [discrete (also known as categorical or qualitative)](/python/discrete-color/). This means that numeric strings must be parsed to be used for continuous color, and conversely, numbers used as category codes must be converted to strings.
+
+For example, in the `tips` dataset, the `size` column contains numbers:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
+                 title="Numeric 'size' values mean continous color")
+
+fig.show()
+```
+
+Converting this column to strings is very straightforward:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+df["size"] = df["size"].astype(str)
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
+                 title="String 'size' values mean discrete colors")
+
+fig.show()
+```
+
+If you have stringified numbers you can convert back just as easily:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+df["size"] = df["size"].astype(str)
+df["size"] = df["size"].astype(float)
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
+                 title="Numeric 'size' values mean continous color")
+
+fig.show()
+```
+
+### Color Scales in Plotly Express
+
+By default, Plotly Express will use the color scale from the active [template](/python/templates/)'s `layout.colorscales.sequential` attribute, and the default active template is `plotly` which uses the `Plasma` color scale. You can choose any of the [built-in color scales](/python/builtin-colorscales/), however, or define your own.
+
+Here is an example that creates a scatter plot using Plotly Express, with points colored using the Viridis color scale.
 
 ```python
 import plotly.express as px
@@ -55,26 +106,26 @@ fig = px.scatter(df, x="sepal_width", y="sepal_length",
 fig.show()
 ```
 
-It is also possible to specify colorscales by name. Here is an example that specifies the Magma colorscale by name, as a string
+It is also possible to specify color scales by name. Here is an example that specifies the `Inferno` color scale by name, as a string
 
 ```python
 import plotly.express as px
 df = px.data.iris()
 fig = px.scatter(df, x="sepal_width", y="sepal_length",
-                 color="sepal_length", color_continuous_scale='Magma')
+                 color="sepal_length", color_continuous_scale='Inferno')
 
 fig.show()
 ```
 
-### Reversing a predefined colorscale
+### Reversing a built-in color scale
 
-You can reverse a predefined colorscale by appending `_r` to its name, for colorscales given either as a string or a `plotly` object.
+You can reverse a [built-in color scale](/python/builtin-colorscales/) by appending `_r` to its name, for color scales given either as a string or a `plotly` object.
 
 ```python
 import plotly.express as px
-df = px.data.iris()
-fig = px.scatter(df, x="sepal_width", y="sepal_length",
-                 color="sepal_length", color_continuous_scale='Magma_r')
+df = px.data.gapminder().query("year == 2007").sort_values(by="lifeExp")
+fig = px.bar(df, y="continent", x="pop", color="lifeExp", orientation="h",
+             color_continuous_scale='Bluered_r', hover_name="country")
 
 fig.show()
 ```
@@ -84,11 +135,154 @@ import plotly.express as px
 data = [[1, .3, .5, .9],
         [.3, .1, .4, 1],
         [.2, .8, .9, .3]]
-fig = px.imshow(data, color_continuous_scale=px.colors.diverging.Tealrose_r)
+fig = px.imshow(data, color_continuous_scale=px.colors.sequential.Cividis_r)
+fig.show()
+```
+
+### Explicity Constructing a Color scale
+
+The Plotly Express `color_continuous_scale` argument accepts explicitly-constructed color scales as well:
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="sepal_length",
+                 color_continuous_scale=["red", "green", "blue"])
+
+fig.show()
+```
+
+The example above provided a list of CSS colors to construct a scale, which inferred the reference points to be evenly spaced, but specific reference points can be provided as well. The following example has the same result:
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="sepal_length",
+                 color_continuous_scale=[(0, "red"), (0.5, "green"), (1, "blue")])
+
+fig.show()
+```
+
+### Constructing a Discrete or Discontinuous Color Scale
+
+You can create a discrete color scale, with discontinuous color, by setting the same reference point twice in a row. This is useful for example with chart types that don't support discrete colors, like [Parallel Coordinates plots](/python/parallel-coordinates-plot/). See below for how to customize tick text.
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.parallel_coordinates(df, color="species_id",
+                             color_continuous_scale=[(0.00, "red"),   (0.33, "red"),
+                                                     (0.33, "green"), (0.66, "green"),
+                                                     (0.66, "blue"),  (1.00, "blue")])
+fig.show()
+```
+
+### Explicitly setting a Color Range
+
+When using the range of the input data as the color range is inappropriate, for example when producing many figures which must have comparable color ranges, or to clip the color range to account for outliers, the Plotly Express `range_color` argument can be used. Here we clip the top of the color range above the lower range of the data and extend it below the lower range of the data:
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="sepal_length", range_color=[5,8])
+
+fig.show()
+```
+
+### Setting the Midpoint of a Color Range for a Diverging Color scale
+
+Diverging color scales have a well-defined midpoint color, and are best-used when that midpoint is mapped to a meaningful data value. The `color_continuous_midpoint` argument to most Plotly Express functions is used for this. It cannot be used with `range_color` because setting it forces the color range to be centered on the midpoint while including the entire dataset. This means that for asymmetric data distributions, not all colors in the color scale will appear in the figure.
+
+For example, a diverging color scale could be used to highlight points with a higher and lower value than the median in a choropleth map like this:
+
+```python
+import plotly.express as px
+
+df = px.data.gapminder().query("year == 2007")
+avg_lifeExp = (df['lifeExp']*df['pop']).sum()/df['pop'].sum()
+
+fig = px.choropleth(df, locations="iso_alpha", color="lifeExp",
+                    color_continuous_scale=px.colors.diverging.BrBG,
+                    color_continuous_midpoint=avg_lifeExp,
+                    title="World Average Life Expectancy in 2007 in years was %.1f" % avg_lifeExp)
+fig.show()
+```
+
+### Hiding or Customizing the Plotly Express Color Bar
+
+Plotly Express binds all traces to [`layout.coloraxis`](/python/reference/#layout-coloraxis), rather than using trace-specific color axes. This means that the color bar can configured there, for example it can be hidden:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.density_heatmap(df, x="total_bill", y="tip", title="No color bar on this density plot")
+
+fig.update_layout(coloraxis_showscale=False)
+
+fig.show()
+```
+
+You can also configure the title, size, placement and tick marks and labels on a color bar:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.density_heatmap(df, x="total_bill", y="tip", title="Customized color bar on this density plot")
+
+fig.update_layout(coloraxis_colorbar=dict(
+    title="Number of Bills per Cell",
+    thicknessmode="pixels", thickness=50,
+    lenmode="pixels", len=200,
+    yanchor="top", y=1,
+    ticks="outside", ticksuffix=" bills",
+    dtick=5
+))
+
+fig.show()
+```
+
+### Customizing Tick Text on Discrete Color Bars
+
+This is the same example as the Parallel Coordinates plot above, with customized tick text for species:
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.parallel_coordinates(df, dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+                             color="species_id", range_color=[0.5, 3.5],
+                             color_continuous_scale=[(0.00, "red"),   (0.33, "red"),
+                                                     (0.33, "green"), (0.66, "green"),
+                                                     (0.66, "blue"),  (1.00, "blue")])
+
+fig.update_layout(coloraxis_colorbar=dict(
+    title="Species",
+    tickvals=[1,2,3],
+    ticktext=["setosa","versicolor","virginica"],
+    lenmode="pixels", len=100,
+))
+fig.show()
+```
+
+### Customizing Tick Text on Logarithmic Color Bars
+
+You can customize text on a logarithmic color bar to make it more readable:
+
+```python
+import plotly.express as px
+import numpy as np
+
+df = px.data.gapminder().query("year == 2007")
+fig = px.scatter(df, y="lifeExp", x="pop", color=np.log10(df["pop"]), hover_name="country", log_x=True)
+
+fig.update_layout(coloraxis_colorbar=dict(
+    title="Population",
+    tickvals=[6,7,8,9],
+    ticktext=["1M", "10M", "100M", "1B"],
+))
 fig.show()
 ```
 
-### Custom Discretized Heatmap Colorscale
+### Custom Discretized Heatmap Color scale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -142,7 +336,7 @@ fig.add_trace(go.Heatmap(
 fig.show()
 ```
 
-### Colorscale for Scatter Plots
+### Color scale for Scatter Plots with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -170,7 +364,7 @@ fig.add_trace(go.Scatter(
 fig.show()
 ```
 
-### Colorscale for Contour Plot
+### Color scale for Contour Plot with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -189,7 +383,7 @@ fig.add_trace(go.Contour(
 fig.show()
 ```
 
-### Custom Heatmap Colorscale
+### Custom Heatmap Color scale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -222,9 +416,9 @@ fig.add_trace(go.Heatmap(
 fig.show()
 ```
 
-### Setting the Midpoint of a Diverging Colorscale
+### Setting the Midpoint of a Diverging Color scale with Graph Objects
 
-The following example uses [marker.cmid](https://plot.ly/python/reference/#scatter-marker-cmid) attribute to set the mid-point of the color domain by scaling 'cmin' and/or 'cmax' to be equidistant to this point. It only has impact when [marker.color](https://plot.ly/python/reference/#scattercarpet-marker-line-color) sets to a numerical array, and 'marker.cauto' is `True`.
+The following example uses the [marker.cmid](https://plot.ly/python/reference/#scatter-marker-cmid) attribute to set the mid-point of the color domain by scaling 'cmin' and/or 'cmax' to be equidistant to this point. It only has impact when [marker.color](https://plot.ly/python/reference/#scattercarpet-marker-line-color) sets to a numerical array, and 'marker.cauto' is `True`.
 
 ```python
 import plotly.graph_objects as go
@@ -255,7 +449,7 @@ fig = go.Figure(go.Heatmap(
 fig.show()
 ```
 
-### Custom Contour Plot Colorscale
+### Custom Contour Plot Color scale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -279,9 +473,9 @@ fig.add_trace(go.Contour(
 fig.show()
 ```
 
-### Custom Colorbar Title, Labels, and Ticks
+### Custom Color bar Title, Labels, and Ticks with Graph Objects
 
-Like axes, you can customize the colorbar ticks, labels, and values with `ticks`, `ticktext`, and `tickvals`.
+Like axes, you can customize the color bar ticks, labels, and values with `ticks`, `ticktext`, and `tickvals`.
 
 ```python
 import plotly.graph_objects as go
@@ -312,9 +506,9 @@ fig.add_trace(go.Heatmap(
 fig.show()
 ```
 
-### Share Color Axis
+### Sharing a Color Axis with Graph Objects
 
-This example shows how traces can share colorbars. To share colorscale information in multiple subplots, you can use [coloraxis](https://plot.ly/javascript/reference/#scatter-marker-line-coloraxis).
+To share colorscale information in multiple subplots, you can use [coloraxis](https://plot.ly/javascript/reference/#scatter-marker-line-coloraxis).
 
 ```python
 import plotly.graph_objects as go
@@ -332,7 +526,7 @@ fig.update_layout(coloraxis = {'colorscale':'viridis'})
 fig.show()
 ```
 
-### Logarithmic Colorscale
+### Logarithmic Color scale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
diff --git a/doc/python/discrete-color.md b/doc/python/discrete-color.md
new file mode 100644
index 00000000000..c80d9552788
--- /dev/null
+++ b/doc/python/discrete-color.md
@@ -0,0 +1,233 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: "1.2"
+      jupytext_version: 1.3.1
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+  language_info:
+    codemirror_mode:
+      name: ipython
+      version: 3
+    file_extension: .py
+    mimetype: text/x-python
+    name: python
+    nbconvert_exporter: python
+    pygments_lexer: ipython3
+    version: 3.6.8
+  plotly:
+    description: How to use and configure discrete color sequences, also known as categorical or qualitative color scales.
+    display_as: file_settings
+    has_thumbnail: true
+    ipynb: ~notebook_demo/187
+    language: python
+    layout: base
+    name: Discrete Colors
+    order: 28
+    permalink: python/discrete-color/
+    thumbnail: thumbnail/heatmap_colorscale.jpg
+    v4upgrade: true
+---
+
+### Discrete vs Continuous Color
+
+In the same way as the X or Y position of a mark in cartesian coordinates can be used to represent continuous values (i.e. amounts or moments in time) or categories (i.e. labels), color can be used to represent continuous or discrete data. This page is about using color to represent **categorical** data using discrete colors, but Plotly can also [represent continuous values with color](/python/colorscales/).
+
+### Discrete Color Concepts
+
+This document explains the following discrete-color-related concepts:
+
+- **color sequences** are lists of colors to be mapped onto discrete data values. No interpolation occurs when using color sequences, unlike with [continuous color scales](/python/colorscales/), and each color is used as-is. Color sequence defaults depend on the `layout.colorway` attribute of the active [template](/python/templates/), and can be explicitly specified using the `color_discrete_sequence` argument for many [Plotly Express](/python/plotly-express/) functions.
+- **legends** are visible representations of the mapping between colors and data values. Legend markers also change shape when used with various kinds of traces, such as symbols or lines for scatter-like traces. [Legends are configurable](/python/legend/) under the `layout.legend` attribute. Legends are the discrete equivalent of [continous color bars](/python/colorscales/)
+
+### Discrete Color with Plotly Express
+
+Most Plotly Express functions accept a `color` argument which automatically assigns data values to discrete colors **if the data is non-numeric**. If the data is numeric, the color will automatically be considered [continuous](/python/colorscales/). This means that numeric strings must be parsed to be used for continuous color, and conversely, numbers used as category codes must be converted to strings.
+
+For example, in the `tips` dataset, the `smoker` column contains strings:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", color="smoker",
+                 title="String 'smoker' values mean discrete colors")
+
+fig.show()
+```
+
+The `size` column, however, contains numbers:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
+                 title="Numeric 'size' values mean continous color")
+
+fig.show()
+```
+
+Converting this column to strings is very straightforward, but note that the ordering in the legend is not sequential by default (see below for how to control discrete order):
+
+```python
+import plotly.express as px
+df = px.data.tips()
+df["size"] = df["size"].astype(str)
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
+                 title="String 'size' values mean discrete colors")
+
+fig.show()
+```
+
+Converting a string column to a numeric one is also quite straightforward:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+df["size"] = df["size"].astype(str) #convert to string
+df["size"] = df["size"].astype(float) #convert back to numeric
+
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
+                 title="Numeric 'size' values mean continous color")
+
+fig.show()
+```
+
+### Color Sequences in Plotly Express
+
+By default, Plotly Express will use the color sequence from the active [template](/python/templates/)'s `layout.colorway` attribute, and the default active template is `plotly` which uses the `plotly` color sequence. You can choose any of the following built-in qualitative color sequences from the `px.colors.qualitative` module, however, or define your own.
+
+```python
+import plotly.express as px
+
+fig = px.colors.qualitative.swatches()
+fig.show()
+```
+
+Color sequences in the `px.colors.qualitative` module are stored as lists of CSS colors:
+
+```python
+import plotly.express as px
+
+print(px.colors.qualitative.Plotly)
+```
+
+Here is an example that creates a scatter plot using Plotly Express, with points colored using the built-in qualitative `G10` color sequence.
+
+```python
+import plotly.express as px
+df = px.data.gapminder()
+fig = px.line(df, y="lifeExp", x="year", color="continent", line_group="country",
+              line_shape="spline", render_mode="svg",
+             color_discrete_sequence=px.colors.qualitative.G10,
+             title="Built-in G10 color sequence")
+
+fig.show()
+```
+
+### Explicitly Constructing a Color Sequence
+
+The Plotly Express `color_discrete_sequence` argument accepts explicitly-constructed color sequences as well, as lists of CSS colors:
+
+```python
+import plotly.express as px
+df = px.data.gapminder().query("year == 2007")
+fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
+             color_discrete_sequence=["red", "green", "blue", "goldenrod", "magenta"],
+             title="Explicit color sequence"
+            )
+
+fig.show()
+```
+
+**_Warning_**: If your color sequence is has fewer colors than the number of unique values in the column you are mapping to `color`, the colors will cycle through and repeat, possibly leading to ambiguity:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", color="day",
+             color_discrete_sequence=["red", "blue"],
+             title="<b>Ambiguous!</b> Explicit color sequence cycling because it is too short"
+            )
+
+fig.show()
+```
+
+### Directly Mapping Colors to Data Values
+
+The example above assigned colors to data values on a first-come-first-served basis, but you can directly map colors to data values if this is important to your application with `color_discrete_map`. Note that this does not change the order in which values appear in the figure or legend, as can be controlled below:
+
+```python
+import plotly.express as px
+df = px.data.gapminder().query("year == 2007")
+fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
+             color_discrete_map={
+                "Europe": "red",
+                "Asia": "green",
+                "Americas": "blue",
+                "Oceania": "goldenrod",
+                "Africa": "magenta"},
+             title="Explicit color mapping")
+
+fig.show()
+```
+
+### Controlling Discrete Color Order
+
+Plotly Express lets you specify an ordering over categorical variables with `category_orders`, which will apply to colors and legends as well as symbols, [axes](/python/axes/) and [facets](/python/facet-plots/). This can be used with either `color_discrete_sequence` or `color_discrete_map`.
+
+```python
+import plotly.express as px
+df = px.data.gapminder().query("year == 2007")
+fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
+             color_discrete_sequence=["red", "green", "blue", "goldenrod", "magenta"],
+             category_orders={"continent": ["Oceania", "Europe", "Asia", "Africa", "Americas"]},
+             title="Explicit color sequence with explicit ordering"
+            )
+
+fig.show()
+```
+
+```python
+import plotly.express as px
+df = px.data.gapminder().query("year == 2007")
+fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
+             color_discrete_map={
+                "Europe": "red",
+                "Asia": "green",
+                "Americas": "blue",
+                "Oceania": "goldenrod",
+                "Africa": "magenta"},
+             category_orders={"continent": ["Oceania", "Europe", "Asia", "Africa", "Americas"]},
+             title="Explicit color mapping with explicit ordering"
+            )
+
+fig.show()
+```
+
+### Using Sequential Scales as Discrete Sequences
+
+In most cases, discrete/qualitative/categorical data values have no meaningful natural ordering, such as in the continents example used above. In some cases, however, there is a meaningful order, and in this case it can be helpful and appealing to use part of a continuous scale as a discrete sequence, as in the following [wind rose chart](/python/wind-rose-charts/):
+
+```python
+import plotly.express as px
+df = px.data.wind()
+fig = px.bar_polar(df, r="frequency", theta="direction", color="strength",
+                   color_discrete_sequence= px.colors.sequential.Plasma[-2::-1],
+                   title="Part of a continuous color scale used as a discrete sequence"
+                  )
+fig.show()
+```
+
+This works because just like in `px.colors.qualitative`, all [built-in continuous color scales](/python/builtin-colorscales/) are stored as lists of CSS colors:
+
+```python
+import plotly.express as px
+
+print(px.colors.sequential.Plasma)
+```