Icon-only controls in Core: four ways of naming them

[Jiwoon-Kim]

Core renders a number of controls whose visible content is an icon and whose
accessible name therefore has to come from somewhere else. I went looking at how
each one does that, expecting small differences, and found that essentially every
one of them was solved separately.

This is an observation rather than a proposal. I have a suggestion at the end, but
the inventory is the part I am confident about.

What is there today

rendering path	element	how it gets its name
Navigation overlay toggle (open / close)	<button>	hardcoded aria-label, added only when hasIcon
Navigation Overlay Close	<button>	hardcoded aria-label
Search, in icon mode	<button>	aria-label from the author's button text
Social Link, front end	<a>	visually hidden <span> text node
Social Link, editor	<button role="button">	the same <span>
Image lightbox close / previous / next	<button>	data-wp-bind--aria-label from Interactivity state

Four mechanisms — a fixed aria-label, an aria-label derived from what the author
wrote, a visually hidden text node, and a runtime binding. The rows are rendering
paths rather than controls: Social Link appears twice because the editor and the
front end render it differently, and the lightbox row covers three buttons.

Two of those rows are worth pausing on.

Social Link is an <a> on the front end and a <button> in the editor. The
editor needs a button because clicking it opens the URL editor rather than
navigating, so the block renders one and duplicates the styling to keep the two
looking alike. Whatever shape a shared primitive takes, it cannot be a button-only
one.

Navigation Overlay Close ignores the author's text. In icon-only mode the
accessible name is the fixed string "Close" rather than what the author wrote. I
have opened #82227 for that
specific bug; it is small and independent of anything here.

They also disagree about styling

core/button                    border, color, dimensions, shadow, spacing, typography
core/navigation-overlay-close  color, spacing, typography
core/search                    border, color, spacing, typography
core/accordion-heading         border, color, shadow, spacing, typography

Navigation Overlay Close is an icon-only control that cannot receive border,
dimensions or shadow — which is to say a theme cannot give it a shape or a
container size, two common visual properties of an icon-only control. I do not
know whether that is deliberate.

And they disagree about how the icon itself is chosen, too: "does this control show
an icon, text, or both" is spelled displayMode: icon|text|both in one block,
buttonUseIcon in another, hasIcon plus icon in a third, and showIcon plus
iconPosition in a fourth.

None of them use the Icon Registry

Today wp_get_icon is called by exactly one block, core/icon. Every control in
the table above carries its own SVG. #81225
and #82062 are addressing that
for Core's internal glyphs, which is the layer underneath this discussion rather
than a duplicate of it: once those glyphs have stable identifiers, something still
has to decide what an icon-only control is.

What I think this suggests

Not a new block, at least not first. What seems missing is a shared contract that
the existing controls could adopt, naming:

• the accessible label, from a single source. Where a control has authorable
  text, the visible text and the accessible name should be the same value seen
  twice, not two strings that can drift. The Navigation Overlay Close bug is
  exactly what happens when they drift.
• the icon, as a registry reference rather than embedded markup. Resolve SVG through Icon Registry #82062 can
  give a later migration stable glyph identifiers to move to; each renderer still
  has to be changed to consume them.
• the tokens an icon-only control needs — size, shape, border, focus,
  hover/pressed/disabled — consistently, rather than whichever subset each block
  happened to declare.
• the semantic variant. A close button and a social link are both icon-only
  controls and are not the same element. Social Link is the case that rules out a
  single button-shaped primitive.

Things I deliberately have not included: a tooltip contract, which brings its own
questions about touch, focus timing and aria-describedby versus
aria-labelledby, and which an icon-only control must be complete without in any
case; and any variant vocabulary (filled, tonal, outlined), which is a design
system's business rather than Core's.

#79057 started from a
linkable Icon block, and the thread suggested shifting the use case toward Button
supporting leading, trailing and icon-only icons, raising the accessibility point
that an icon-only control needs a label. Those are suggestions in that thread
rather than a settled direction; this discussion approaches the same area from the
controls that already exist.

Where I am coming from

I maintain a block theme that implements a design system on top of Core blocks, and
the icon-only controls were where it needed the most private knowledge of Core
markup. The theme separates the three layers this discussion keeps running into —
the glyph, the control that performs an action, and the description of that action
— which is the only reason I noticed they are entangled in Core:

• icon system
• icon button
• tooltip

I am not proposing that Core adopt that system. The separation is the point, not
the visual language.

Questions

1. Is the inconsistency above known and accepted, or is it accumulated drift?
2. Would a shared icon-control contract be welcome, or is per-block handling the
   preference?
3. If shared: does it belong as an internal primitive the existing blocks consume,
   or eventually as something authors can insert?
4. Should the accessible label of an icon-only control always be derived from the
   author's own text where that text exists?