Titles in Dashboard editor (global, section, cards) are easy to understand and configure

[laupalombi]

Problem statement

After adding their cards, someone goes to give the dashboard a heading — a task that sounds trivial — and hits a wall. The problem isn't one thing; the whole title configuration is confusing. First, it's unclear what they're even editing: people bounce between the tab title, the section title, the card title, and the heading block before landing in the right place. Then they're asked to pick a "type" — a Card vs. No card toggle — that produces no visible difference, so they can't tell what they're choosing or why. And once they're in, they're met with raw markdown and a {{ user }} template placeholder, with no plain-text way to just type a heading. People who've never seen markdown freeze, fear breaking something, and several actually do break it and have to close without saving. What should be a five-second task becomes one of the most error-prone and stressful moments in the entire dashboard creation flow.

Community signals

This came directly out of moderated usability research (8 participants, think-aloud protocol, on HA 2025.4). Configuring the heading was a universal blocker — all 8 participants struggled with it. It tied for the highest error count of any task in the study (median 3 errors), matching the very first card users add. That's telling: the first card is hard because users arrive with no mental model at all, whereas adding a title should be simple. Time ran up to ~3m50s for what was framed as "just add a title." The friction showed up across the whole interaction:

• Not knowing which title to edit: participants went to the section, the tab, or the view config first (P3, P5, P6, P7 all reported confusion between section / card / tab / heading titles)

• The card "type" choice: "Clicked on Card vs No card and didn't see the difference in preview." (P0); "Didn't understand the card vs text concept." (P4)
• Markdown as a wall: "I don't know markdown. Instant pushback." (P2); "Completely lost in markdown. Had to be guided." (P1); "This is too technical." (P5)
• Overall bewilderment: "I have no idea what I'm doing in this Title card." (P4); "It is too complex to change text." (P0)

Two participants broke the markdown on their first attempt and had to close without saving.

Scope & Boundaries

In scope

• Rework the heading/title configuration so a first-time user can add a heading without understanding card types or syntax
• Clarify which "title" is being edited (tab vs section vs card vs heading block) so users don't hunt for the right place
• Remove or rethink the confusing "Card vs No card" type toggle (or make its effect obvious)
• Provide a plain-text default for the heading (and subheading), with markdown, template variables, and Show Code as an opt-in advanced path rather than the first thing a new user sees

Not in scope

• A broader rework of the card editor tabs (e.g. Features / Interactions naming) — separate opportunities
• The "By Entity" vs "By Card" default — separate opportunity
• Section layout / sizing controls — separate opportunity
• Removing markdown power-user capability (it stays; it's just no longer the default surface)

Foreseen solution

Rework the heading configuration into a simple, structured editor that a first-timer can use without making upfront choices about card types or learning syntax. In practice that means: a clear, single place to set the heading; a plain-text field (heading + optional subheading) as the default; removing or clarifying the "type" toggle so users aren't asked to decide something they don't understand; and keeping markdown and template variables ({{ user }}) behind an "advanced" / "edit as markdown" affordance for power users who want dynamic content — without creating another Show-Code-style dead end. Design is in progress.

Risks & open questions

• How to preserve markdown/template power without cluttering the default experience or recreating a "no way back" trap
• Whether this is solved standalone or folds into a broader card-editor UX audit, since several research findings share root causes.
• Back-compatibility for existing headings that already contain markdown

Appetite

No response

Execution issues

No response

Decision log

Date	Decision	Outcome

[tobbexiv]

In the end, that dialog is a markdown card. I'd say that the points mentioned in regard to the dialog itself, also apply for the usual markdown card. So, I would suggest to have this as broad as including the markdown card dialog.

Remove or rethink the confusing "Card vs No card" type toggle (or make its effect obvious)

No for removal for me. It has an effect and therefore is valid. I also see the difference in the preview. But, the border added for the card option is very near to the border of the preview itself. Having a bigger margin could help here.

Provide a plain-text default for the heading (and subheading), with markdown, template variables, and Show Code as an opt-in advanced path rather than the first thing a new user sees

Plain text removes the option to have a personal greating. Also the formatting is then gone. Especially as currently you are not forced to habe a heading with a specific format. In my opinion, a WYSIWYG editor would be a better option. That way, the user has full formatting options while at the same time they are not bothered by the markdown syntax. It would be even possible to provide a (limited?) template syntax like usernames that can be handled by anyone. Usually they also come with a natove option to switch between sourcecode and display mode.

While there are other alternatives, I use TinyMCE as example as I worked with it in the past:

• markdown support is available as plugin
• Custom plugin(s) can be used to parse the text and convert Jinja templates in a way that they are editable via popup (like URLs). Either as plain text or even with a UI. Similar, control steuctures could be done for control steuctures, ... Additionally, menu buttons could be added for the most common scenarios (adding username, current time, ...).
• if done to a certain extent, this could be reused in other places (automations: variables editor and places where a value is passed as template; twmplate playground; ...). Making Home Assistant more approachable for non-technical users as they don't need to learn Jinja but instead have a WYSIWYG editor.

[mbb365]

Here is the starting point Figma file.