Remove "Advanced" and "Expert" terminology from Home Assistant

[frenck]

Problem statement

Home Assistant uses the words "Advanced" and "Expert" in various places across the UI, integration configuration flows, service action descriptions, and documentation. These labels create a psychological barrier: they implicitly tell users that certain features are not for them unless they meet some undefined skill threshold. For a platform whose 2026 goal is to become meaningfully more approachable, this kind of gatekeeping language works directly against us.

The problem is not the features themselves; it is the framing. Labelling something "advanced" or "expert" does two things that hurt us:

1. It discourages exploration. Users who are perfectly capable of using a feature may skip it because the label suggests they are not qualified. This is especially damaging for new users during their first days, when confidence is fragile and discoverability matters most.
2. It can feel alienating. Telling someone they need "expert" knowledge to use a configuration option implies a hierarchy of users. This framing is at odds with our values of empowerment and inclusion. The user who just installed Home Assistant yesterday deserves the same respect as the one who has been running it for five years.

This is distinct from, but closely related to, the removal of the Advanced mode toggle (roadmap #54). Opportunity #54 focuses on removing the binary gate mechanism. This opportunity focuses on the broader language problem: every instance of "Advanced" or "Expert" as a label, heading, section title, tooltip, or documentation term across the entire product surface needs to be identified, evaluated, and replaced with neutral, descriptive alternatives.

This directly supports the 2026 goal "Make Home Assistant More Approachable": reducing confusion and friction in the first days of use, making common tasks discoverable without deep technical knowledge, and ensuring Home Assistant is increasingly perceived as approachable rather than intimidating.

Scope & Boundaries

In scope

• Audit of all UI strings across frontend, core, supervisor, and apps (add-ons) that use "Advanced", "Expert", or similar skill-implying terminology
• Audit of all integration configuration flows (config flows and options flows) for skill-implying labels on steps, sections, or field descriptions
• Audit of service/action descriptions that use these terms
• Replacement of each occurrence with neutral, descriptive wording (e.g., "More options", "Additional settings", "All settings", "Show details", or context-specific phrasing that describes what the options actually do)
• Audit and update of official documentation (home-assistant.io) to remove or replace these terms
• Addition of a terminology guideline to the developer documentation and frontend contribution guidelines, explicitly forbidding the use of "Advanced", "Expert", and similar skill-gating language in UI strings, and providing approved alternatives
• Addition of a documentation style guideline forbidding these terms in user-facing docs

Not in scope

• Removal of the Advanced mode toggle itself (covered by roadmap #54)
• Redesigning information architecture or progressive disclosure patterns (that is a separate, larger UX initiative)
• Third-party integrations, custom components, or community-maintained documentation (we can only control first-party content)
• Changing the admin/non-admin user distinction

Foreseen solution

1. Terminology audit: Search across all relevant repositories (frontend, core, supervisor, add-ons, official documentation, developer documentation) for UI strings, config flow step names, section labels, tooltips, and documentation headings containing "Advanced", "Expert", or equivalent skill-gating terms. Produce a comprehensive inventory.

2. Per-occurrence replacement: For each occurrence, choose a neutral, descriptive replacement. The guiding principle is: describe what the options do, not who they are for. Examples:

   • "Advanced settings" becomes "Additional settings" or "More options"
   • "Expert mode" becomes a contextual description or is simply removed
   • "For advanced users" in documentation becomes a description of what the section covers, or is removed entirely
   • Where a collapsed/expandable section is used, the label should describe the content (e.g., "Network settings", "Logging options") rather than the audience

3. Developer guidelines: Add a clear rule to the developer documentation (integration development docs) and the frontend contribution guidelines stating that "Advanced", "Expert", and similar terms must not be used in user-facing strings. Provide a list of approved alternatives and the reasoning behind the policy.

4. Documentation guidelines: Add the same rule to the documentation contribution guidelines for home-assistant.io, with examples of before/after phrasing.

5. Review gate: Consider adding a CI check or linting rule for new translation strings that flags these terms before they enter the codebase.

Community signals

• Community WTH 2020: "Advanced mode is too hidden": Users consistently report frustration that essential features are locked behind a poorly discoverable toggle. The broader sentiment is that the "Advanced" framing itself is the problem, not just discoverability.
• Frontend #23019: "Advanced mode toggle needs better description": The toggle description says "Unlocks advanced features" and links to a 2019 blog post. The issue highlights how the term has become meaningless and unhelpful.
• Multiple community forum posts (1, 2, 3, 4) show a recurring pattern where users struggle to find or understand the "Advanced mode" concept, and community answers routinely start with "Do you have Advanced mode enabled?" as troubleshooting boilerplate.
• Community: "Why does Configuration > Users require Advanced Mode?": A user points out that basic administrative functions like managing users should not be gated behind a label that implies they are not for regular use.
• The general UX direction of HA (2025/2026 dashboard and automation improvements) is trending toward more intuitive, human-friendly language. The continued use of "Advanced" and "Expert" is inconsistent with this trajectory.

Risks & open questions

• Volume of occurrences: The audit may surface a large number of instances across many repositories and integrations, especially in translation strings. A phased rollout (frontend first, then core integration flows, then documentation) may be more practical than a single sweep.
• Translation impact: Replacing UI strings means updating translations across all supported languages. Coordination with the translation community will be needed.
• Integration config flows: Individual integrations may use "Advanced" in their config flow step names or descriptions. The long tail of integrations means this could take multiple releases to fully clean up.
• Community perception: Some users self-identify as "advanced" users and may initially resist the removal of these labels. Clear communication about why the change is being made (inclusion, not dumbing down) will be important.
• Guideline enforcement: Without a linting rule or CI check, new occurrences may creep back in. The guideline needs teeth, not just documentation.

Appetite

Small to medium: roughly 1 to 2 cycles. The bulk of the work is the audit and the individual string replacement PRs. The guideline additions to developer and documentation contribution guides are straightforward. If a CI linting rule is pursued, that adds a small amount of tooling work.

Execution issues

Populated once a bet is approved.

Decision log

Date	Decision	Outcome
March 11, 2026	Created opportunity to address skill-gating terminology across all of Home Assistant, complementing the Advanced mode toggle removal in roadmap #54	Pending