| name | docs-lens-chart-page |
| version | 1.0.2 |
| description | Create or update a Lens chart documentation page following Elastic docs conventions. Use when writing a new chart type page (pie, bar, metric, gauge, heat map, etc.) or updating an existing one in explore-analyze/visualize/charts/. Relies on lens-chart-settings for verifying UI labels against source code. |
| context | fork |
| allowed-tools | Read, Grep, Glob, Edit, WebFetch |
| sources | ["https://github.com/elastic/kibana/tree/main/x-pack/platform/plugins/shared/lens/public/visualizations"] |
Creating Lens Chart Documentation Pages
Use these instructions when creating or updating a documentation page for a Kibana Lens chart type in explore-analyze/visualize/charts/.
Before writing: verify settings against source code
Use the lens-chart-settings skill to verify all UI labels, option values, and rendering order against the Kibana source code before documenting them. Never guess UI labels.
Research resources
Kibana source code paths
| Chart type | Source path |
|---|
| Partition (pie, donut, treemap, mosaic, waffle) | x-pack/platform/plugins/shared/lens/public/visualizations/partition/ |
| XY (bar, line, area) | x-pack/platform/plugins/shared/lens/public/visualizations/xy/ |
| Metric | x-pack/platform/plugins/shared/lens/public/visualizations/metric/ |
| Datatable | x-pack/platform/plugins/shared/lens/public/visualizations/datatable/ |
Many visualizations use shared components (in shared_components/) that accept different props per chart. Always check the visualization-specific wrapper to see which props are passed, rather than assuming all shared component options are available.
EUI data visualization guidelines
Existing content to check
- Main Lens page:
explore-analyze/visualize/lens.md — check for content to reference or deduplicate.
- Other chart pages:
explore-analyze/visualize/charts/*.md — follow established patterns.
- Shared snippets:
explore-analyze/_snippets/lens-*.md — reuse instead of duplicating.
Key snippets:
| Snippet | Purpose |
|---|
lens-prerequisites.md | Prerequisites paragraph (data views, ES|QL mode) |
lens-rank-by-options.md | Top values rank-by options |
lens-value-advanced-settings.md | Advanced settings for value/metric dimensions |
lens-breakdown-advanced-settings.md | Breakdown advanced settings |
lens-histogram-settings.md | Date histogram settings |
line-chart-legend-settings.md | Legend settings including Statistics (line/area) |
line-chart-style-settings.md | Style settings (line/area) |
When creating a new chart page, update lens.md to link to it and remove any duplicated content.
File location and frontmatter
Place the file at explore-analyze/visualize/charts/<chart-type>.md with this frontmatter:
---
navigation_title: <Chart type> charts
description: Instructions and best practices for building <chart type> charts with Kibana Lens in Elastic.
---
Chart-specific dimensions
| Chart type | Primary dimensions | Additional dimensions |
|---|
| Pie / Donut | Slice by, Metric | (none) |
| Bar / Line / Area | Horizontal axis, Vertical axis | Breakdown |
| Metric | Primary metric | Secondary metric, Maximum value |
| Gauge | Metric | Minimum value, Maximum value, Goal |
| Table | Metrics, Rows | Split metrics by |
Page structure
Follow this exact section order. Every chart page uses it consistently.
1. Title and introduction
# Build <chart type> charts with {{kib}}
- One paragraph (2-3 sentences): what the chart does and when it's useful. Focus on purpose.
- Weave in specific actionable constraints (e.g., "works best with a maximum of 6 slices"). Skip generic advice.
- Do not create a separate "When to use" section.
- A line:
You can create <chart type> charts in {{kib}} using [**Lens**](../lens.md).
- A hero image of a representative example.
2. "Build a chart" section
Include the prerequisites snippet before the stepper:
:::{include} ../../_snippets/lens-prerequisites.md
:::
Then use the stepper directive:
::::::{stepper}
:::::{step} Access Lens
**Lens** is {{kib}}'s main visualization editor. You can access it:
- From a dashboard: On the **Dashboards** page, open or create the dashboard where you want to add a <chart type> chart, then add a new visualization.
- From the **Visualize library** page by creating a new visualization.
:::::
:::::{step} Set the visualization to <Chart type>
New visualizations often start as **Bar** charts.
Using the **Visualization type** dropdown, select **<Chart type>**.
:::::
:::::{step} Define the data to show
[Chart-specific data configuration steps]
:::::
:::::{step} Customize the chart to follow best practices
[Best practices as a definition list]
:::::
:::::{step} Save the chart
- If you accessed Lens from a dashboard, select **Save and return** to save the visualization and add it to that dashboard, or select **Save to library** to add the visualization to the Visualize library and reuse it later.
- If you accessed Lens from the Visualize library, select **Save**. A menu opens and offers you to add the visualization to a dashboard and to the Visualize library.
:::::
::::::
Key conventions:
- Access Lens and Save the chart steps are identical across all chart pages. Copy them verbatim.
- Define the data to show lists numbered steps for chart-specific dimensions, then "Optionally:" for additional dimensions. Link dimension names to their settings sections (e.g.,
[**Slice by**](#slice-by-settings)).
- Customize the chart uses definition list format. List 4-6 actionable best practices. End with a line pointing to the full settings reference.
3. Advanced scenarios (optional)
Only include when teaching a non-obvious technique users wouldn't discover on their own:
- Using formulas (e.g., computing error rates as a percentage)
- Configuring multiple metrics for completion progress (waffle)
- Setting up dynamic bounds or goals from data (gauge)
- Defining custom color ranges (heat map)
- Configuring color bands with thresholds (gauge)
Do NOT create scenarios that are just "use the chart with different fields". For simpler chart types, the Examples section is sufficient.
When including scenarios:
- Each scenario gets its own
## or ### heading with an anchor ID.
- Use concrete examples based on Kibana Sample Data when possible.
Sample data considerations
- The
response field in web logs is a text field — KQL filters must use pattern matching (response: 2*), not numeric comparisons.
- In sample ecommerce data,
taxful_total_price and taxless_total_price are identical.
- Multiple comparable numeric fields are rare. When sample data doesn't support a scenario, use a conceptual example with realistic field names and add a
:::note explaining users need to adapt to their data.
4. " settings" section
Document every configuration option in the Lens editor, organized by dimension/panel.
Structure each dimension as:
### <Dimension> settings [<dimension>-settings]
Within each dimension, use two top-level definition list entries: **Data** and **Appearance**.
Data:
- List all available functions/aggregation types.
- For each function, document the Field selector first, then function-specific sub-options as nested bullets.
- Field selector conventions:
- Top values: Supports up to 4 fields. Multiple fields create multi-term grouping. Fields can be reordered by dragging.
- Date histogram: Single date field only.
- Intervals: Single numeric field only.
- Filters: No field selector (KQL queries reference fields directly).
- Reuse shared snippets wherever applicable.
Appearance:
- List visual options: Name, Value format, Color, Series color, Color mapping, etc.
After dimension-specific settings, add a ### General layout section for global settings ({icon}`brush` Style and legend). Split into #### Style settings and #### Legend settings as needed.
Legend settings vary by chart type:
| Setting | XY charts | Partition charts | Notes |
|---|
| Visibility | Yes | Yes | Auto / Show / Hide |
| Position | Yes | No | Partition charts don't pass location |
| Statistics | Yes | No | Controlled by defaultLegendStats |
| Nested legend | No | Yes (>1 group) | Multiple Group by dimensions required |
| Label truncation | Yes | Yes | |
| Width | Yes | Yes | UI label is "Width", not "Legend size" |
5. " examples" section
- 2-4 real-world examples using Kibana Sample Data.
- Use definition list format with bold example title.
- Structure each example:
* Example based on: <sample data set name>- Configuration keys as bullet points (Slice by, Metric, Style, Legend, etc.)
- An image of the result, sized with
"=60%" or "=70%"
- Showcase different features (e.g., basic config, donut variant, filters, multiple metrics).
Chart-page-specific formatting
For general syntax, refer to the docs-syntax-help skill. These conventions are specific to chart pages:
Images
- Store at
explore-analyze/images/<image-name>.png
- Reference with:
- Sizing:
"=50%" for smaller inline images, "=60%" for examples, "=70%" for settings screenshots.
- Alt text should be descriptive, not "screenshot".
Icons
| Icon | Syntax | Usage |
|---|
| Style/brush | {icon}\brush`` | Style settings panel |
| Layer settings | {icon}\app_management`` | Layer settings (9.3+/Serverless) |
| Actions menu | {icon}\boxes_horizontal`` | Layer actions menu (9.0-9.2) |
| Add layer | {icon}\plus_in_square`` | Add layer button |
For the legend icon, use: 
Cross-references
- Other chart types:
[bar charts](bar-charts.md)
- Lens page:
[**Lens**](../lens.md)
- Lens features:
[Assign colors to terms](../lens.md#assign-colors-to-terms)
- Sample data:
[sample data](/manage-data/ingest/sample-data.md)
Internal links
Link from steps to settings sections:
2. Configure the [**Slice by**](#slice-by-settings) dimension.
3. Configure the [**Metric**](#metric-settings) dimension.
Link from best practices to advanced scenarios when relevant.
Variables
Use {{kib}} (Kibana), {{es}} (Elasticsearch), {{data-source}} (data view / data source).
Checklist
