charts og descriptions

sites/docs/pages/components/charts/annotations/index.md

@@ -1,12 +1,13 @@
 ---
 title: Annotations
+description: Add important context directly to a chart - highlight areas, or specific points to make it easier for your reader to draw insights.
 sidebar_position: 9
 queries: 
 - orders_by_month.sql
 - orders_by_category_2021.sql
 ---
 
-Annotations help you add important context directly within a chart - highlight important dates, time periods, or specific points on a chart to make it easier for your audience to pull insights from the information.
+Use annotations to add important context directly to a chart - highlight areas, or specific points to make it easier for your reader to draw insights.
 
 ## At a glance
 

sites/docs/pages/components/charts/area-chart/index.md

@@ -1,11 +1,14 @@
 ---
 title: 'Area Chart'
+description: Track how a metric with multiple series changes over time, or a continuous range. 
 sidebar_position: 1
 queries:
 - orders_by_month.sql
 - orders_by_category_2021.sql
 ---
 
+Use area charts to track how a metric with multiple series changes over time, or a continuous range. Area charts emphasize changes in the sum of series over the individual series.
+
 <DocTab>
     <div slot='preview'>
         <AreaChart 

sites/docs/pages/components/charts/bar-chart/index.md

@@ -1,5 +1,6 @@
 ---
 title: Bar Chart
+description: Compare a metric across a small number of categories. 
 sidebar_position: 1
 queries: 
 - orders_by_month.sql
@@ -8,6 +9,8 @@ queries:
 - categories_by_channel.sql
 ---
 
+Use bar or column charts to compare a metric across categories. Bar charts are best with a small number of categories and series, and should generally start at 0.
+
 <DocTab>
     <div slot='preview'>
         <BarChart 

sites/docs/pages/components/charts/box-plot/index.md

@@ -1,10 +1,13 @@
 ---
 title: Box Plot
+description: Summarize the distribution and range of a metric around the median value.
 sidebar_position: 1
 queries: 
 - sales_distribution_by_channel.sql
 ---
 
+Use box plots to summarize the distribution and range of a metric around the median value.
+
 <DocTab>
     <div slot='preview'>
         <BoxPlot 

sites/docs/pages/components/charts/bubble-chart/index.md

@@ -1,10 +1,13 @@
 ---
 title: Bubble Chart
+description: Display categorical data across three metrics. The X and Y position, and the size of the bubble each represent a different metric for the category.
 sidebar_position: 1
 queries:
 - price_vs_volume.sql
 ---
 
+Use bubble charts to display categorical data across three metrics. The X and Y position, and the size of the bubble each represent a different metric for the category.
+
 <DocTab>
     <div slot='preview'>
         <BubbleChart 

sites/docs/pages/components/charts/calendar-heatmap/index.md

@@ -1,11 +1,14 @@
 ---
 title: Calendar Heatmap
+description: Display how a single metric varies over weeks and months in a familar GitHub-style format
 sidebar_position: 5
 queries:
 - orders_by_day.sql
 - orders_by_day_2021.sql
 ---
 
+Use calendar heatmaps to display how a single metric varies over weeks and months.
+
 <DocTab>
     <div slot='preview'>
         <CalendarHeatmap 

sites/docs/pages/components/charts/custom-echarts/index.md

@@ -1,6 +1,7 @@
 ---
 sidebar_position: 98
 title: Custom ECharts
+description: Evidence charts are based on ECharts, a powerful and flexible open source charting library. You can configure any ECharts graph directly using the ECharts component.
 ---
 
 Our chart library is based on [ECharts](https://echarts.apache.org/examples/en/index.html), a powerful and flexible open source JavaScript chart library. We use many of the features in ECharts, and combine them with custom data transformation, logic, and theming.

sites/docs/pages/components/charts/echarts-options/index.md

@@ -1,8 +1,11 @@
 ---
 sidebar_position: 999
 title: ECharts Options
+description: Evidence charts are based on ECharts. Pass options to ECharts directly using the echartsOptions property.
 ---
 
+Evidence charts are based on ECharts. Pass options to ECharts directly using the echartsOptions property.
+
 <Alert status=warning>
 
 `echartsOptions` allow you to customize your chart with any combination of eCharts config options. Many config combinations can result in "broken" looking charts. Proceed with caution, and test your charts, particularly at different screen widths.

sites/docs/pages/components/charts/funnel-chart/index.md

@@ -1,8 +1,11 @@
 ---
 title: Funnel Chart
+description: Display how a single metric changes across a series of stages. Funnel charts are widely used for visualizing conversion.
 sidebar_position: 6
 ---
 
+Use funnel charts to display a single metric across a series of stages. Funnel charts are widely used for visualizing conversion.
+
 ```sql funnel_data
 select * from (
     select 150 as customers, 'Show' as stage, 1 as stage_id

sites/docs/pages/components/charts/heatmap/index.md

@@ -1,8 +1,11 @@
 ---
 title: Heatmap
+description: Show patterns in a single metric across two categorical dimensions, using colour to indicate size.
 sidebar_position: 5
 ---
 
+Use heatmaps to show patterns in a single metric across two categorical dimensions, using colour to indicate size.
+
 ```orders
 select category, dayname(order_datetime) as day, dayofweek(order_datetime) as day_num, count(*) as order_count from needful_things.orders
 group by all

sites/docs/pages/components/charts/histogram/index.md

@@ -1,8 +1,11 @@
 ---
 title: Histogram
+description: Display the distribution of a metric along a continuous range, aggregated into buckets.
 sidebar_position: 1
 ---
 
+Use histograms to display the distribution of a metric along a continuous range, aggregated into buckets.
+
 ```sql orders
 select * from needful_things.orders limit 1000
 ```

sites/docs/pages/components/charts/line-chart/index.md

@@ -1,8 +1,11 @@
 ---
 title: Line Chart
+description: Display how one or more metrics over time. Line charts are suitable for plotting a large number of data points on the same chart.
 sidebar_position: 1
 ---
 
+Use line charts to display how one or more metrics over time. Line charts are suitable for plotting a large number of data points on the same chart.
+
 ```sql orders_by_month
 select order_month as month, sum(sales) as sales_usd0k, count(1) as orders from needful_things.orders
 group by all

sites/docs/pages/components/charts/mixed-type-charts/index.md

@@ -1,8 +1,13 @@
----
+
 title: Mixed-Type Charts
+description: Display multiple series types on the same chart, for example a bar for an amount, and a line for a related percentage.
 sidebar_position: 99
 ---
 
+Use mixed-type charts to display multiple series types on the same chart, for example a bar for an amount, and a line for a related percentage. 
+
+Mixed-type charts can be confusing, so use them sparingly. To add reference lines, areas or points to a chart instead, see [Annotations](/components/charts/annotations).
+
 <Alert status=info>
 
 The easiest way to create mixed-type charts is setting up [a secondary y-axis in `LineChart`](/components/charts/line-chart#secondary-axis-with-bar) or a [secondary axis in `BarChart`](/components/charts/bar-chart#secondary-axis-with-line)

sites/docs/pages/components/charts/sankey-diagram/index.md

@@ -1,9 +1,10 @@
 ---
 title: Sankey Diagram
+description: Display flows of a metric transferring between different categories.
 sidebar_position: 6
 ---
 
-The SankeyDiagram component accepts a query and displays a flow from one set of values to another.
+Use Sankey diagrams to display flows of a metric transferring between different categories.
 
 To display a flow with multiple levels, like these examples, see [Mutli-level](#multi-level) below.
 

sites/docs/pages/components/charts/scatter-plot/index.md

@@ -1,10 +1,13 @@
 ---
 title: Scatter Plot
+description: Show the correlation between two metrics for categorical values, or a set of samples.
 sidebar_position: 1
 queries:
 - price_vs_volume.sql
 ---
 
+Use scatter plots to show the correlation between two metrics for categorical values, or a set of samples.
+
 <DocTab>
   <div slot='preview'>
     <ScatterPlot 

sites/docs/pages/components/charts/sparkline/index.md

@@ -1,8 +1,11 @@
 ---
 title: Sparkline
+description: Display a compact visual representation of a single metric over time.
 sidebar_position: 9
 ---
 
+Use sparklines to display a compact visual representation of a single metric over time or a continuous range.
+
 ```sql orders_by_month
 select order_month as month, sum(sales) as sales_usd0k, count(1) as orders from needful_things.orders
 group by all