Brickheart

Brickheart website — navigation structure and accessible submenu implementation

: Written by a human with AI assistance.

Objective

Review and update the Brickheart website navigation to provide a clear, accessible hierarchy of top-level menu items and nested submenu links.

Important: Inspect the actual source files before editing. The code snippets and navigation hierarchy below are proposals, not confirmation of the current implementation.

1. Proposed navigation structure

Use the following as an initial information architecture.

Home

  • Home is the logo

Tools

  • LDraw Lite
  • LPlace
  • LFrame

Purpose: give visitors a clear route to the project's tools.

Learn

  • Getting Started
  • Tutorials
  • Command Reference
  • FAQ / Troubleshooting

Purpose: help new users understand how to use the tools.

Accessibility

  • Accessibility Overview
  • Supported Input Methods
  • Compatibility and Known Limitations
  • Accessibility Statement

Purpose: document the project's accessibility objectives, supported interaction methods, tested assistive technologies and known limitations.

Project

  • About
  • Contact / Feedback
  • Development Blog (dev.brickheart.org/blog, english only)

Purpose: explain the project, provide a feedback route and communicate development status.

Footer

Keep the existing legal and utility links, including:

  • Privacy
  • Accessibility Statement
  • AI Use Policy
  • Change language and settings

Keep footer navigation separate from primary navigation where appropriate.

2. Required submenu interaction model

I prefer top-level items with children to be expanders, not links.

For example, “Tools” must not navigate to a landing page when clicked. It should be a button that expands or collapses the child links.

Top-level items without children remain ordinary links.

Use semantic HTML:

  • <nav> for the navigation region, with an accessible label.
  • <ul> and <li> for the hierarchical lists.
  • <button type="button"> for parent items that expand submenus.
  • <a> for actual destinations.
  • aria-expanded="false" or "true" on each submenu button.
  • aria-controls referencing the corresponding submenu's unique ID.
  • The HTML hidden attribute on collapsed submenus.

Native links, buttons and lists are preferred.

Expected keyboard behaviour

  1. Tab moves through visible top-level links and expander buttons in normal document order.
  2. Enter or Space on an expander toggles its submenu.
  3. When expanded, Tab reaches its child links.
  4. Enter on a child link navigates to its destination.
  5. When collapsed, child links must not be reachable by Tab.
  6. Escape should close an open submenu and return focus to its expander, if Escape behaviour is implemented.
  7. Focus must remain visible, and expanding a submenu must not unexpectedly move focus.
  8. The same functionality must work with pointer, touch and keyboard input.

Use real buttons rather than clickable <li> or <span> elements.

Parent and child behaviour

  • A parent with children is an expander button only; it is not a link.
  • A child is a normal link to its page.
  • An item without children remains a normal link.
  • The submenu button must update aria-expanded whenever the submenu opens or closes.
  • The submenu's hidden state must stay synchronized with the button state.
  • Use unique, stable submenu IDs derived safely from the configuration.
  • Decide and document whether multiple submenus may remain open simultaneously. Prefer consistency with the existing site design.
  • Support appropriate focus and interaction behaviour on mobile and desktop.

3. Existing code conventions to preserve

The current navigation renderer includes code of this form:

const topNav = cfg.topNav.map((n) => {
  const here = outPath === `${lang.folder}/${n.path}`;
  return html`<li><a href="${rel(outPath, `${lang.folder}/${n.path}`)}"${here ? raw(' aria-current="page"') : ''}>${U[n.key]}</a></li>`;
});

The footer renderer similarly uses cfg.bottomNav, U[n.key], rel(...), raw(...), and the html template helper.

Preserve these conventions unless inspection shows a concrete reason to change them:

  • cfg.topNav and cfg.bottomNav as configuration-driven navigation.
  • U[n.key] for translated labels.
  • rel(outPath, ...) for relative URL calculation.
  • lang.folder for language-specific routes.
  • raw(...) for intentional raw HTML attributes, as supported by the existing template helper.
  • aria-current="page" for active destination links.
  • The existing build system, module conventions and formatting.

4. Accessibility and styling requirements

  • Ensure the navigation is usable without a mouse.
  • Provide visible focus indicators for links and buttons.
  • Do not rely exclusively on hover to open a submenu.
  • Ensure the expanded/collapsed state is conveyed to screen readers.
  • Keep the focus order logical and predictable.
  • Ensure collapsed submenus are genuinely hidden from keyboard and assistive technology navigation.
  • Provide sufficient contrast for text, buttons, separators and focus indicators.
  • Support narrow screens, zoom and reflow.
  • Preserve language switching and right-to-left layouts.
  • Use logical CSS properties such as margin-inline where appropriate.
  • Avoid invalid HTML, including placing <nav> directly inside a <p>.
  • Avoid duplicate IDs, inaccessible icon-only controls and placeholder links.
  • Keep separators such as middle dots decorative and out of link accessible names.

Target WCAG 2.2 Level AA as the intended standard.