docs: add custom panels for dashboards (#7627)

[florent-leborgne]

Summary

This PR addresses #7627 with the following changes:

• explore-analyze/visualize/custom-panels.md (new, type: how-to): documents the custom panel type. Covers when to use it, how the template and optional ES|QL query work, creation from the dashboard or from an Agent Builder conversation (one Create a custom panel section with two starting points), editing in the flyout, chat refinement with version cards, Liquid template syntax with a short sample, the theme CSS properties, dashboard interactions, the time filter connection with ?_tstart and ?_tend, and limitations.
• explore-analyze/visualize/custom-panel-examples.md (new, child page): five complete examples, each with a screenshot followed by Prompt (when generated with chat), Query, and Template dropdowns. Sankey diagram and logo banner generated with Agent Builder chat, plus a hand-written multi-metric card with CSS-only tabs, a narrative summary, and a status board.
• explore-analyze/images/custom-panels-*.png (9 new): the Sample Logs Ops Center dashboard built from custom panels (intro), the Add to dashboard flyout with Custom highlighted, the Create custom panel flyout, a chat-created Sankey next to its conversation, and one screenshot per example. All captured on a main build on 2 September 2026 with the templates as published.
• explore-analyze/visualize.md: adds a Custom panels row to the panel types table, tagged stack: preview 9.6+ and serverless: preview.
• explore-analyze/ai-features/agent-builder/agent-builder-dashboards-and-visualizations.md: adds a Custom panels row to Supported panel types with a reciprocal link to the new page.
• explore-analyze/dashboards/create-dashboards-using-ai.md: adds a tagged paragraph stating that agents can also create custom panels.
• explore-analyze/toc.yml: registers the new page after the Vega page, with the examples page as its child.

All UI labels were verified against Kibana origin/main on 2 September 2026 and updated for the copy changes merged in elastic/kibana#288823 on 3 September 2026 (Edit Custom panel configuration, Custom panel attachment) (i18n defaultMessage strings in x-pack/platform/plugins/shared/custom_content). Behavior claims trace to the plugin README, fetch_esql_data.ts, fill_template.ts, prepare_html.ts, edit_custom_content_flyout.tsx, handle_panel_preview.ts, and the agent_builder_dashboards generation guidance. The export-portability claim for inline SVG relies on the existing image panels page and the file saved object being non-exportable.

A live test pass on a main build (2 September 2026) covered the Add menu path, the edit flyout, chat creation and refinement including version cards, dashboard interactions, the limitations list, and every example on the examples page. Findings that changed the text: the edit action is a hover action rather than a panel menu entry, the time filter hint depends on ?_tstart/?_tend first and @timestamp second, an invalid query or template shows Failed to render panel, a missing template column renders empty or 0, the newest version card's Preview is a no-op by design, and CSS-only tabs with hidden radio inputs work inside a panel.

Hold until product confirms

Documented as if fully live, per the docs owner's decision. Not true on main yet:

• The Add → Custom entry is hidden behind dashboard.customContent.enabled (default false) since [Custom content] Temporarily hide from the UI kibana#287768. The "Start from the dashboard" procedure and the Add row descriptions assume it is visible again. Do not merge before the Presentation team re-enables it or confirms the final entry point.

Reviewer-check items

• The theme table lists the nine --cc-color-* properties injected at HEAD. Draft [Custom content] Applies basic eui styling, improves guidelines kibana#287778 adds more (spacing, font, radius). Extend the table if that PR merges before release.
• The Vega page lists Sankey charts as a Vega use case. The custom panels pages say Sankey diagrams are complex to build as Vega visualizations and offer a custom panel as an alternative. Confirm the wording is acceptable to the Visualizations team.
• The two generated examples (Sankey, banner) are published verbatim as the agent produced them after refinement, including hard-coded colors in the banner. The page says why. The Sankey template is 339 lines and sits in a dropdown. The banner's single-line SVG path was wrapped at 120 characters because docs-builder's callout regex times out on very long code lines.
• All screenshots use the dark theme. Say so if you'd rather have them in the light theme.

Resolves

Closes #7627

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

Tool(s) and model(s) used: Claude Code, Claude Fable 5.1. Two example templates were generated by Elastic Agent Builder (Claude Opus 4.8) during testing.

---

AI-generated draft created with Claude Code (Claude Fable 5.1).
Review all generated content for factual accuracy before merging.

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: queued.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

[github-actions]

🔍 Preview links for changed docs

• explore-analyze/ai-features/agent-builder/agent-builder-dashboards-and-visualizations.md
• explore-analyze/dashboards/create-dashboards-using-ai.md
• explore-analyze/visualize.md
• explore-analyze/visualize/custom-panel-examples.md
• explore-analyze/visualize/custom-panels.md

[github-actions]

Elastic Docs Style Checker (Vale)

Summary: 1 warning found

⚠️ Warnings (1): Fix when the suggestion improves clarity or correctness.

File	Line	Rule	Message
explore-analyze/visualize/custom-panels.md	37	Elastic.Spelling	'Gantt' is a possible misspelling.

---

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.

[github-actions]

Docs review summary

Focus areas

• Style and clarity: two Vale-flagged wording issues addressed inline (may → can/might, In addition → also). The new pages (custom-panels.md, custom-panel-examples.md) read clearly, use active voice/second person, and follow UI-writing conventions (bold UI labels, Select/In the field, enter phrasing, arrow menu paths).
• Jargon: no unexplained Elastic-internal jargon found in the changed prose. Terms like ES|QL, Fast mode, and Liquid are linked or defined on first use.
• Frontmatter and applies_to: both new pages have description, applies_to, and products set correctly; applies_to syntax (stack: preview 9.6+, serverless: preview) matches the pattern used elsewhere in the repo (e.g., 9.5+). No issues found.
• Content type fit: custom-panels.md is declared and structured as a how-to (requirements, numbered creation/edit procedures, limitations). custom-panel-examples.md is a reference-style examples page without a type, consistent with sibling pages like transform-examples.md and ml-nlp-examples.md, so not flagged.
• Contradictions: No contradictions found. The claim that Sankey diagrams are complex to build in Vega is consistent with the published Vega/Vega-Lite page, which already lists Sankey charts among unsupported Vega use cases.
• Parent issue satisfaction: Satisfied for the docs scope described in the PR body (new how-to page, examples page, cross-links from the agent-builder and dashboards-with-AI pages, and a new panel-types table row). Note the PR itself flags two "hold until product confirms" items (the Add → Custom entry point being behind a currently-disabled flag, and a pending Kibana label-rename PR) — these are product-side blockers the author already called out, not a docs gap.

Notes

• One inline comment (visualize.md line 41, "In addition") falls in the SLO Alerts row, which the PR diff didn't touch — flagged only because it was in the pre-fetched Vale output; feel free to disregard if out of scope for this PR.
• Did not independently re-verify the live-UI behavior claims (hover-to-edit action, Failed to render panel error text, time-filter hint) against a running Kibana build; the PR body documents these as verified against origin/main and a live test pass, which is the expected level of rigor for this change.

Generated by Docs review agent for #8169 · copilot · sonnet50 · 119.6 AIC · ⌖ 25.8 AIC · ⊞ 18.1K

Comments that could not be inline-anchored

explore-analyze/ai-features/agent-builder/agent-builder-dashboards-and-visualizations.md:22

For best results with {{esql}}-heavy dashboard generation, use a higher-tier model such as Claude 4.6 Opus. Current testing shows that Claude 4.6 Sonnet can require more corrections for generated dashboard queries.

Vale flags may here (Elastic.WordChoice). Use can/might instead of may, since may isn't a UI term in this sentence.

explore-analyze/visualize.md:41

Vale flags "In addition" here (Elastic.Wordiness). Replace with "also" for a more minimalist, direct phrasing per the voice-and-tone guide.

[leemthompo]

I approve the developer documentation component of this pull request, which is quite minimal

[vishaangelova]

Looks good! A couple of nits maybe.