The Navigation block may be the biggest bottleneck holding back the block theme ecosystem

[Jiwoon-Kim]

Navigation block theming is disproportionately difficult

I want to share a practical block-theme developer experience report.

This is not intended as promotion, but as a reproducible example of the problem. I maintain a pure block theme, Axismundi, and a small companion plugin for navigation icons: Axismundi Navigation Icons.

The Navigation Icons plugin is not required to reproduce the layout issue described below. I include it as a related example: core Navigation does not provide a general navigation-item icon slot, so adding a Material-style icon treatment requires a companion implementation alongside the theme.

My goal is to treat WordPress core blocks as design-system components. The theme binds Material Design-inspired tokens to the block-theme infrastructure, then maps and customizes core blocks so that the site can operate as one coherent design system.

Navigation has been, by far, the hardest core block to do this with.

Other complex blocks, including Table, require careful work. But Navigation is in a different category. It combines many rendering modes and contexts:

• horizontal and vertical layouts
• responsive overlays and mobile menus
• saved Navigation menus and Page List output
• submenu visibility modes
• nested submenu levels
• buttons, links, disclosure controls, and inline SVG icons
• editor canvas versus front-end rendering
• different markup shapes for seemingly similar navigation structures

The result is that a theme author often has to style implementation details rather than stable component parts. A selector that works for a Navigation submenu may not reach a Page List parent item. A selector that works on the front end may behave differently in the editor. Replacing or consistently styling a disclosure icon can require targeting a particular SVG structure or a very specific DOM path.

I understand why this happened: Navigation has a large state space and must support many use cases. But the current theming experience is disproportionately expensive. It is difficult to reason about, difficult to test comprehensively, and fragile across markup changes.

A concrete example is core/page-list inside core/navigation. It looks like a set of ordinary Navigation items, but it renders as a nested list and therefore becomes one flex child of the Navigation container rather than participating as peer items. This means a layout choice such as justify-content: space-between can distribute the outer Navigation items and the entire Page List as separate groups, while the Page List distributes its own children differently.

The visual result is inconsistent spacing and wrapping even though the editor presents all of these entries as one Navigation surface. Solving that reliably currently requires theme authors to understand and target internal markup differences rather than style a stable Navigation-item contract.

For reference, these are the two stylesheets where this work has accumulated in my theme:

• blocks.navigation.css
• blocks.navigation-submenu.css

I would be interested in discussion around making Navigation more themeable through stable styling contracts, for example:

• documented component-part selectors or CSS custom properties
• consistent markup contracts for Navigation and Page List items
• stable hooks for submenu/disclosure icons
• clearer separation between navigation item, submenu trigger, submenu menu, and responsive-overlay responsibilities
• stronger editor/front-end parity for layout and state

I am not asking for a particular implementation here. I mainly want to communicate that Navigation is currently the largest source of complexity in building a serious design system on top of a pure block theme, and to ask whether improving its theming surface could become a developer-experience priority.

The Navigation block is the biggest obstacle I encountered while building a production-ready block theme
https://designbusan.ai.kr/showcase/theme-blocks/

[Jiwoon-Kim]

The concrete Page List defect is now tracked in #82207.

It is a small rendering bug with a small possible fix, but it also makes the broader concern in this discussion more precise. core/navigation has to infer whether each heterogeneous child belongs to its item list by inspecting that child's rendered HTML for an LI tag. core/page-list then has a different wrapper and layout shape from core/navigation-link, despite materializing the same visible kind of destination.

That is why a theme cannot reliably target a single Navigation-item concept today. It has to account for a block tree, a rendered DOM tree, and sometimes a dynamically generated list tree that do not have the same shape.

I think a near-term improvement would be a documented editor/frontend rendering contract for:

• navigation item
• item link or submenu trigger
• submenu container
• generated/source item
• responsive overlay
• icon slot

This does not require deciding a new storage format first. It would let Navigation, Page List, and the existing heterogeneous allowed children expose the same themeable parts while preserving their current authoring model.

The Icon Registry work in #81225 / #82062 is a useful precedent: it separates a stable semantic UI identifier from the underlying SVG implementation. Navigation needs the analogous separation for its structural parts.

I will follow up separately on the longer-term question of a structured Navigation Resource model. That proposal should not block either the Page List fix or a stable rendering contract.

[Jiwoon-Kim]

One concrete block-theme perspective on the scope of these changes:

This is not only a theoretical distinction for Axismundi. Its Navigation styling currently has to account separately for Page List descendants, submenu state classes, responsive-overlay markup, and a responsive-toggle variant which Core does not identify semantically.

For example:

• the theme explicitly reaches .wp-block-pages-list__item because Page List destinations are rendered below a separate wrapper rather than as peer Navigation items;
• it currently identifies one responsive-toggle SVG variant by a private path[d="..."] selector, because the control has no stable semantic identifier yet.

The relevant implementation is public here:

• https://github.com/Jiwoon-Kim/axismundi/blob/main/products/distributables/themes/axismundi/assets/styles/blocks.navigation.css#L9
• https://github.com/Jiwoon-Kim/axismundi/blob/main/products/distributables/themes/axismundi/assets/styles/blocks.navigation.css#L494
• https://github.com/Jiwoon-Kim/axismundi/blob/main/products/distributables/themes/axismundi/assets/styles/blocks.navigation-submenu.css

I would distinguish three outcomes rather than treat them as one rewrite:

1. Correct the Page List structure. This resolves the invalid ul > ul output in Navigation with a top-level Page List produces invalid ul > ul markup #82207 and lets generated top-level pages participate in the same flex/list layout as adjacent items. It removes the immediate need to special-case Page List merely to obtain ordinary top-level item behavior.

2. Publish a Navigation part contract. Stable editor/frontend parts for an item, trigger, submenu, generated item, overlay, and icon slot would let a block theme map a design system to Navigation semantics instead of reproducing Core's incidental DOM structure. This is also where the Icon Registry direction in Allow Core blocks to resolve internal UI SVGs through the Icon Registry #81225 / Resolve SVG through Icon Registry #82062 matters: a semantic icon identifier is a much safer theme boundary than SVG geometry.

3. Consider a resource model separately. A structured Navigation resource would not by itself make a theme's CSS disappear or automatically permit a renderer replacement. Its value is to separate menu data from the current block renderer and editor tree, so those capabilities can be designed deliberately rather than remain consequences of serialized inner blocks.

For a block-theme author, the first two stages are the immediate interoperability work. The third is a longer-term data-model discussion and should not delay either of them.