docs: add dashboard design best practices to existing pages (#5445)#6330
Closed
florent-leborgne wants to merge 5 commits into
Closed
docs: add dashboard design best practices to existing pages (#5445)#6330florent-leborgne wants to merge 5 commits into
florent-leborgne wants to merge 5 commits into
Conversation
Bake design guidance into the pages where users already work, instead of adding a standalone best-practices page: - create-dashboard: new "Plan your information hierarchy" step between populating and organizing panels (KPIs at top, charts in middle, detail tables at bottom). - arrange-panels: new "Tips for sizing panels" subsection covering height by content type, row consistency, and using collapsible sections to separate primary from secondary content. - lens: new "Tips for clear visualizations" tip about descriptive panel titles and hiding redundant axis titles via the Axis title dropdown (None). - text-panels: tip clarifying that text panels are for context and links, not section headers — prefer collapsible sections and descriptive chart titles for structure. Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
Contributor
Contributor
✅ Vale Linting ResultsNo issues found on modified lines! The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale. |
Replace the inline tip blocks and the mid-stepper insertion with top-level "Best practices" H2 sections placed where readers naturally land for that topic: - create-dashboard: H2 between Requirements and the create steps, covering information hierarchy. Original step numbering restored. - arrange-panels: H2 at the end of the page covering panel sizing and arrangement habits. - lens: H2 right after the chart-type comparison table covering panel titles and axis titles. - text-panels: H2 right after the page intro covering when text panels add value and what to use instead for section headers. Best-practices sections cross-reference each other bidirectionally. Co-authored-by: Cursor <cursoragent@cursor.com>
- Shorten H2 to `## Best practices` to match the other three pages in this PR and parallel #6329's noun-phrase style. - Cross-link the width bullet to the new `Dashboard grid layout` section added in #6329 so readers can find concrete column widths in one click. Co-authored-by: Cursor <cursoragent@cursor.com>
Move the panel sizing/arranging best-practices section to PR #6329 so it lives inside the new "Dashboard grid layout" section instead of as a standalone section at the bottom of the page. The cross-link in `create-dashboard.md` still points at `#arrange-panels-best-practices`, which #6329 will create. Co-authored-by: Cursor <cursoragent@cursor.com>
florent-leborgne
added a commit
that referenced
this pull request
May 6, 2026
Adds an H3 Best practices subsection inside the new Dashboard grid layout H2, covering: - Match panel height to content type - Keep heights consistent within a row - Use width to signal importance (refers to the column reference table above) - Separate primary from secondary content with collapsible sections Cross-references back to Best practices for dashboard design in `create-dashboard.md` (added in PR #6330). Originally drafted in #6330, moved here so all panel sizing / arranging guidance lives in a single section with the grid mechanics. Co-authored-by: Cursor <cursoragent@cursor.com>
florent-leborgne
added a commit
that referenced
this pull request
May 6, 2026
The link from `arrange-panels.md` Best practices to `create-dashboard.md#create-dashboard-best-practices` pointed at an anchor that only exists in #6330. Removing it lets this PR merge independently. The reverse direction (`create-dashboard.md` → `arrange-panels.md` Best practices) is kept in #6330 and will resolve once this PR lands. Co-authored-by: Cursor <cursoragent@cursor.com>
The target section was renamed to 'Dashboard grid layout and best practices' in #6329, with the H2 anchor 'dashboard-grid-layout'. The old 'arrange-panels-best-practices' anchor no longer exists, so update the link target and label to match. Co-authored-by: Cursor <cursoragent@cursor.com>
Member
Author
Member
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR addresses #5445 by adding explicit
## Best practicesH2 sections to three pages users naturally read while building dashboards, instead of scattering tip blocks. Each section is placed where the reader is already looking for that topic:explore-analyze/dashboards/create-dashboard.md— new## Best practicesbetween Requirements and Create a new dashboard, covering information hierarchy (KPIs at top, charts in the middle, detail tables at the bottom). Sits before the steps so readers think about layout before clicking through them. Cross-references the panel-sizing best practices added in docs: document the dashboard 48-column grid (#5449) #6329.explore-analyze/visualize/lens.md— new## Best practicesdirectly after the chart-type comparison table, covering descriptive panel titles and hiding redundant axis titles via the Axis title dropdown set to None.explore-analyze/visualize/text-panels.md— new## Best practicesright after the page intro, listing what text panels are good for (descriptions, instructions, links, images) and pointing readers to collapsible sections and descriptive chart titles for section headers instead.Guidance is sourced from the
kibana-dashboardsagent skill in elastic/agent-skills-sandbox and kept qualitative. The 48-column grid mechanics and exact panel widths from the skill are documented separately in #6329.The Axis title dropdown label and its None option were verified against the current Lens source (
x-pack/platform/plugins/shared/lens/public/shared_components/vis_label.tsxandaxis/title/toolbar_title_settings.tsxonmain).Resolves
Closes #5445
Merge order
Land #6329 first. This PR contains a cross-link from
create-dashboard.mdtoarrange-panels.md#arrange-panels-best-practices, an anchor created in #6329. Once #6329 is onmain, this PR can merge with the link resolved.