Every field can explain itself

[frenck]

Problem statement

Home Assistant's UI contains hundreds of form fields across integration config flows, options flows, automation editors, helper configuration, and system settings. Many of these fields use technical or domain-specific terminology that new (and sometimes experienced) users struggle to understand.

We already have a mechanism to help: the data_description key in strings.json allows integration developers to attach a short description to any form field, rendered inline directly below the input. This is a good foundation, but it has three limitations that prevent it from reaching its potential:

1. Space pressure harms the UI. Because descriptions are rendered inline below the field, longer or more detailed explanations push content down, create visual clutter, and make forms feel overwhelming and text-heavy. As a result, developers are discouraged from adding meaningful guidance, often omitting it entirely or keeping it so brief it is not actually helpful. The UI punishes thoroughness.
2. Plain text only. Field descriptions do not support markdown. This means developers cannot use basic formatting (bold, code, lists) to make descriptions scannable, and cannot emphasize key information. A description that would benefit from structure ends up as a wall of plain text.
3. No structured way to link to documentation. There is currently no first-class mechanism to attach a "Learn more" link to a field that points to relevant documentation. Users who need more context must leave the UI and search the docs themselves, which breaks the flow and increases the chance they give up or misconfigure something.

The result: users encounter fields they do not understand, have limited help available in context, and either guess, search external resources, or abandon the task.

This opportunity directly supports Make Home Assistant More Approachable. Contextual help on form fields reduces confusion during setup and early use, helps users reach a "first success" state more quickly, and makes common tasks discoverable without deep technical knowledge. Every config flow and options flow in the system benefits.

For comparison, products like UniFi's network management interface solve this with a small info icon ("i") next to each field that opens a rich tooltip or popover containing a detailed explanation and a "Learn more" link to full documentation. This pattern keeps the default UI clean while making help available exactly where and when it is needed.

Example screenshot from UniFi for illustration:

Scope & Boundaries

In scope

• Markdown support for data_description. The existing data_description field in strings.json should render markdown, allowing developers to use basic formatting (bold, code, lists) in field descriptions without any changes to how descriptions are provided today.
• A "Learn more" URL per field. A new field (e.g., learn_more_url) in selectors that allows integration developers to attach a documentation link to any form field. The frontend renders this as a clickable "Learn more" link.
• A new frontend presentation: the info popover. A small "?" or "i" icon rendered next to the field label that, when clicked/tapped, opens a popover/balloon containing the field's data_description (now with markdown) and the "Learn more" link (if provided). This replaces the current inline rendering for fields that have descriptions, keeping the default form view clean and uncluttered.
• Gradual adoption. Start with core settings and the most commonly used integration flows; expand over time as developers add descriptions and links to their integrations.

Not in scope

Changing how data_description is provided in strings.json (the existing developer API stays the same, we just render it better)

• Rewriting all existing field descriptions across every integration (that is an ongoing effort once the infrastructure exists)
• AI-generated or dynamically generated help text
• Dashboard/card-level tooltips for end users (a related but separate feature request)
• Changes to the documentation site itself
• Overhaul of our design system

Foreseen solution

Build on top of the existing data_description system with three changes:

1. Render data_description as markdown. Today, data_description values are rendered as plain text (in some places) below a field. By supporting markdown rendering, developers can use bold, inline code, and lists to make descriptions more scannable and useful, without any changes to how they provide the data. Every integration that already provides a data_description benefits immediately.

2. Add a learn_more_url field to selectors. A new optional property on selectors that accepts a URL to relevant documentation. When present, the frontend renders a "Learn more" link alongside the field description. This gives users a direct path from any form field to its documentation, closing the loop that currently requires them to search externally.

3. Move descriptions into an info popover. Instead of rendering field descriptions inline below the input (which consumes vertical space and creates visual clutter), introduce a small "?" or "i" icon next to the field label. Clicking or tapping this icon opens a popover/balloon that contains the markdown-rendered data_description and the "Learn more" link (if available). Fields without a data_description remain unchanged. On touch devices, the popover opens on tap and can be dismissed by tapping outside; no hover-only patterns.

The net effect: the default form view becomes cleaner (no inline text below every field), while richer and more useful help is one tap away. The UniFi screenshot attached to this issue illustrates this exact pattern in practice.

Progressive cleanup. Once the popover exists, existing inline descriptions that are overly long or that try to cram documentation links into plain text can gradually be migrated to take advantage of markdown formatting and the "Learn more" link, resulting in a cleaner and less text-heavy UI across the board.

Community signals

This is a recurring theme across community feedback channels:

• WTH tooltips / drop-downs for inline documentation of dashboard elements (Month of WTH, Nov 2024): Users asking for inline help and contextual documentation across the UI
• WTH Tooltip when hovering over a helper? (Month of WTH, Dec 2024): Users confused by helper types, wanting explanations directly in the UI
• Tooltip for help info (frontend#3883): Long-standing feature request for help tooltips on entities and form fields
• Tooltip for help info (frontend Discussion #11187): Discussion on implementing contextual help tooltips
• Tooltip Option On Cards (Feature Request, Jan 2023): Users wanting explanatory tooltips on UI elements
• Tooltip for entities (Feature Request, Dec 2024): Request for user-facing tooltips with additional info

While some of these signals focus on dashboard-level tooltips (which is out of scope here), the underlying need is the same: users want contextual help where they are, not somewhere else.

Risks & open questions

• Adoption of learn_more_url. The markdown and popover changes improve things immediately for every integration that already provides a data_description. However, populating learn_more_url across hundreds of integrations is a long-tail effort. How do we incentivize and guide integration developers to add these links? Should it become part of the Integration Quality Scale?
• Translation burden. Richer descriptions (taking advantage of markdown) may mean longer translatable strings. Is the translation community able to keep up, or do we need a fallback strategy?
• Mobile popover UX. Popovers on small screens need careful design to avoid covering the field they explain. How do we handle this gracefully?
• Documentation URL maintenance. If documentation pages move, learn_more_url links break. Do we need a redirect/alias system, or is this an acceptable maintenance cost?
• Inline vs. popover transition. Moving descriptions from inline to popover changes user expectations. Should we provide a transition period where both are visible, or switch cleanly?

Appetite

Small to medium: roughly 1 cycle for the frontend component, selector integration, and strings support. Adoption across integrations is an ongoing effort beyond the initial build.

Execution issues

To be populated once a bet is approved.

Decision log

Date	Decision	Outcome
2026-03-11	Created opportunity based on recurring community feedback and approachability goal alignment. The core idea: build on the existing data_description system by adding markdown support, a learn_more_url field on selectors, and a popover-based presentation to replace inline rendering.	Submitted for shaping