---
name: bolt-menu
description: >-
  Use this skill whenever configuring, structuring, or verifying Bolt CMS navigation menus in config/bolt/menu.yaml (header 'main', footer columns, submenus, multilingual labels, /#anchor formatting, and CTA classes) and rendering them through the Twig Component/Container templates (header with dropdowns and mobile drawer, footer columns, nav components, logo).
title: bolt-menu
canonical_url: https://skilld.dev/gh/vondry/bolt-skills/bolt-menu
last_updated: 2026-11-12T13:08:42.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [examples/menu_catalog.yaml](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/menu_catalog.yaml), [examples/menu_conditional.yaml](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/menu_conditional.yaml), [examples/menu_landing.yaml](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/menu_landing.yaml), [examples/templates/components/brand/logo.twig](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/templates/components/brand/logo.twig), [examples/templates/components/nav/dropdown.twig](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/templates/components/nav/dropdown.twig), [examples/templates/components/nav/item.twig](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/templates/components/nav/item.twig), [examples/templates/containers/footer/_footer.twig](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/templates/containers/footer/_footer.twig), [examples/templates/containers/header/_menu.twig](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/templates/containers/header/_menu.twig), [examples/translations.cs.xlf](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/translations.cs.xlf), [examples/translations.en.xlf](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/examples/translations.en.xlf), [scripts/scaffold.sh](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/scripts/scaffold.sh), [scripts/verify.sh](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-menu/scripts/verify.sh).
>
> If the user asked to install this Skill, run `npx skilld install vondry/bolt-skills/bolt-menu`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/bolt-menu`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/vondry/bolt-skills/bolt-menu) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/bolt-menu`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/bolt-menu --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/bolt-menu --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Bolt CMS Navigation Menus (`bolt-menu`)

This skill defines the architectural rules, configuration standards, and verification runbook for building website navigation in Bolt CMS using `config/bolt/menu.yaml` and consuming it in Twig templates.

---

## Architectural Principles

In Bolt CMS, menus represent the **Information Architecture (IA)** and interface shell of the website. Unlike dynamic editorial content stored in the database, menus live in `config/bolt/menu.yaml` so that navigation remains deterministic, version-controlled in Git, and decoupled from content lifecycles.

```mermaid
flowchart TD
    Config["config/bolt/menu.yaml<br/>(main, footer, submenus)"] --> Builder["Bolt FrontendMenuBuilder<br/>(resolves locale label & URIs)"]
    Builder --> TwigFunc["Twig: menu_array('main')<br/>menu_array('footer')"]
    TwigFunc --> ContainerHeader["Smart Container<br/>containers/header/_menu.twig<br/>- splits CTAs<br/>- hides the homepage link on the homepage"]
    TwigFunc --> ContainerFooter["Smart Container<br/>containers/footer/_footer.twig<br/>- columns, contacts, socials & legal links"]
    ContainerHeader --> CompNavItem["Pure Component<br/>components/nav/item.twig<br/>locale_link(item.uri)"]
    ContainerHeader --> CompDropdown["Pure Component<br/>components/nav/dropdown.twig<br/>accessible accordion"]
    ContainerHeader --> MobileDrawer["Mobile Drawer<br/>[data-mobile-menu=drawer]"]
    ContainerHeader --> Logo["Pure Component<br/>components/brand/logo.twig"]
    CompDropdown --> MenuTs["js/src/menu.ts (bolt-theme-init)<br/>accordions + drawer"]
    MobileDrawer --> MenuTs
```

### Core Menus Defined in `config/bolt/menu.yaml`
1. **`main`**: The primary top navigation for the header. Contains top-level links, dropdown submenus, and optional Call-to-Action (CTA) items.
2. **`footer`**: Multi-column footer links organized as category headings with child `submenu:` lists.

---

## Critical Rules for `config/bolt/menu.yaml`

### 1. Mandatory Root Slash on Anchors (`/#section`)
> [!IMPORTANT]
> **Never write bare anchor links like `#kontakt` or `#sluzby` in `menu.yaml`.**
> Anchor links **must always** start with a leading slash: `/#kontakt`, `/#o-nas`.

**Why?**
- On the **homepage** (`/`), the browser recognizes the same URL base and smoothly scrolls to `<section id="kontakt">` without reloading.
- On a **subpage or record detail page** (e.g. `/zasady-ochrany-osobnich-udaju`, `/blog/novinka`), a bare `#kontakt` link would attempt to find an anchor on the current subpage, failing completely. A link written as `/#kontakt` cleanly navigates back to the homepage and jumps to `#kontakt`.

### 2. Multilingual Label Parity
When a website supports multiple languages (the codes in `app_locales` in `config/services.yaml`), labels in `menu.yaml` must be declared as a per-locale map containing every code:

```yaml
# Good: Localised dictionary matching configured locales
- label: { cs: 'O nás', en: 'About us', de: 'Über uns' }
  link: /o-nas
```

Bolt's `FrontendMenuBuilder` automatically checks the current request locale (`$twig->getHtmlLang()`), resolves the matching key (falling back to the default locale, then to `title`), and returns the translated string in `item.label`.

### 3. Clean Internal Links Without Locale Prefixes
> [!WARNING]
> **Never hardcode language prefixes in links (`/cs/...` or `/en/...`).**
> Always write the canonical clean path (`/o-nas`, `/kontakt`, `/#sluzby`).

In Twig templates, wrap all URLs in `locale_link(item.uri)` (provided by `bolt-runtime-extensions`). The runtime extension dynamically prepends `/<locale>` when not on the default language while leaving the default language clean.

### 4. Classification & Modifier Flags (`class: cta`, `class: has-submenu`)
Use the `class` attribute in `menu.yaml` as semantic behavioral hooks:
- `class: cta`: Marks an item as a primary Call-to-Action button (e.g. "Rezervovat", "Kontakt").
- `class: has-submenu`: Marks an item having nested dropdown children.

In header Twig templates, split the array using Twig filters:
```twig
{% set nav_items  = menu_array('main') %}
{% set cta_items  = nav_items|filter(i => i.class is defined and 'cta' in i.class|split(' ')) %}
{% set link_items = nav_items|filter(i => i.class is not defined or 'cta' not in i.class|split(' ')) %}
```

Classes written in `menu.yaml` are picked up by Tailwind because `css/tailwind/index.css` scans `config/bolt/menu.yaml` (`@source`).

---

## Configuration Recipes

### Recipe A: Anchor-Based Single Page Landing (`menu_landing.yaml`)
Best for single-page service, professional-practice or personal websites, where every section of the homepage is an anchor:

```yaml
# config/bolt/menu.yaml
main:
  - label: { cs: 'Úvod', en: 'Home' }
    link: /
  - label: { cs: 'Služby', en: 'Services' }
    link: /#sluzby
  - label: { cs: 'Jak pracujeme', en: 'How we work' }
    link: /#postup
  - label: { cs: 'Reference', en: 'References' }
    link: /#reference
  - label: { cs: 'Tým', en: 'Team' }
    link: /#tym
  - label: { cs: 'Kontakt', en: 'Contact' }
    link: /#kontakt
    class: cta

# Footer navigation links
footer:
  - label: { cs: 'Navigace', en: 'Navigation' }
    submenu:
      - label: { cs: 'Úvod', en: 'Home' }
        link: /
      - label: { cs: 'Služby', en: 'Services' }
        link: /#sluzby
      - label: { cs: 'Reference', en: 'References' }
        link: /#reference
      - label: { cs: 'Kontakt', en: 'Contact' }
        link: /#kontakt
  - label: { cs: 'Právní informace', en: 'Legal' }
    submenu:
      - label: { cs: 'Zásady ochrany osobních údajů', en: 'Privacy Policy' }
        link: /zasady-ochrany-osobnich-udaju
      - label: { cs: 'Obchodní podmínky', en: 'Terms of Service' }
        link: /obchodni-podminky
```

### Recipe B: Hierarchical Multi-Page Catalog (`menu_catalog.yaml`)
Best for corporate, manufacturing, or e-commerce catalog sites with product groups in a dropdown:

```yaml
# config/bolt/menu.yaml
main:
  - label: { cs: 'O nás', en: 'About us', de: 'Über uns' }
    link: /o-nas
  - label: { cs: 'Produkty', en: 'Products', de: 'Produkte' }
    link: /produkty
    class: has-submenu
    submenu:
      - label: { cs: 'Všechny produkty', en: 'All products', de: 'Alle Produkte' }
        link: /produkty
      - label: { cs: 'Příslušenství', en: 'Accessories', de: 'Zubehör' }
        link: /prislusenstvi
      - label: { cs: 'Náhradní díly', en: 'Spare parts', de: 'Ersatzteile' }
        link: /nahradni-dily
  - label: { cs: 'Služby', en: 'Services', de: 'Leistungen' }
    link: /sluzby
  - label: { cs: 'Reference', en: 'References', de: 'Referenzen' }
    link: /reference
  - label: { cs: 'Kariéra', en: 'Careers', de: 'Karriere' }
    link: /kariera
  - label: { cs: 'Kontakt', en: 'Contact', de: 'Kontakt' }
    link: /kontakt
    class: cta

# --- Footer link columns -----------------------------------------------------
footer:
  - label: { cs: 'Produkty', en: 'Products', de: 'Produkte' }
    submenu:
      - label: { cs: 'Všechny produkty', en: 'All products', de: 'Alle Produkte' }
        link: /produkty
      - label: { cs: 'Příslušenství', en: 'Accessories', de: 'Zubehör' }
        link: /prislusenstvi
      - label: { cs: 'Náhradní díly', en: 'Spare parts', de: 'Ersatzteile' }
        link: /nahradni-dily
      - label: { cs: 'Dokumenty ke stažení', en: 'Downloads', de: 'Downloads' }
        link: /ke-stazeni
  - label: { cs: 'Společnost', en: 'Company', de: 'Unternehmen' }
    submenu:
      - label: { cs: 'O nás', en: 'About us', de: 'Über uns' }
        link: /o-nas
      - label: { cs: 'Reference', en: 'References', de: 'Referenzen' }
        link: /reference
      - label: { cs: 'Kariéra', en: 'Careers', de: 'Karriere' }
        link: /kariera
      - label: { cs: 'Kontakt', en: 'Contact', de: 'Kontakt' }
        link: /kontakt
  - label: { cs: 'Právní informace', en: 'Legal', de: 'Rechtliches' }
    submenu:
      - label: { cs: 'Zásady ochrany osobních údajů', en: 'Privacy Policy', de: 'Datenschutz' }
        link: /zasady-ochrany-osobnich-udaju
```

### Recipe C: Conditional Event / Media Site (`menu_conditional.yaml`)
Best for event, conference or media websites whose homepage sections (programme, performers, tickets) only make sense while their ContentType has published entries. Guard such items in the header template, e.g. `{% setcontent performers = 'performers' limit 1 %}` in the container (inside `{% if config.get('contenttypes/performers') %}`) and skip the `/#ucinkujici` item when `performers` is empty:

```yaml
# config/bolt/menu.yaml
main:
  - label: { cs: 'Úvod', en: 'Home' }
    link: /
  - label: { cs: 'Program', en: 'Programme' }
    link: /#program
  - label: { cs: 'Účinkující', en: 'Performers' }
    link: /#ucinkujici
  - label: { cs: 'Vstupenky', en: 'Tickets' }
    link: /#vstupenky
    class: cta
  - label: { cs: 'O akci', en: 'About the event' }
    link: /#o-akci
  - label: { cs: 'Archiv', en: 'Archive' }
    link: /archiv
  - label: { cs: 'Kontakt', en: 'Contact' }
    link: /#kontakt

footer:
  - label: { cs: 'Akce', en: 'Event' }
    submenu:
      - label: { cs: 'O akci', en: 'About the event' }
        link: /#o-akci
      - label: { cs: 'Program', en: 'Programme' }
        link: /#program
      - label: { cs: 'Účinkující', en: 'Performers' }
        link: /#ucinkujici
      - label: { cs: 'Archiv', en: 'Archive' }
        link: /archiv
  - label: { cs: 'Informace', en: 'Information' }
    submenu:
      - label: { cs: 'Praktické informace a FAQ', en: 'Practical info & FAQ' }
        link: /#faq
      - label: { cs: 'Zásady ochrany osobních údajů', en: 'Privacy Policy' }
        link: /zasady-ochrany-osobnich-udaju
      - label: { cs: 'Kontakt', en: 'Contact' }
        link: /#kontakt
```

The scaffolded recipes are starting points: replace their items with the site's own information architecture.

---

## Twig Integration: Component & Container Architecture

Follow the standard theme architecture from `bolt-theme-init` (Integration Contract in `WORKFLOWS.md`). The master layout `partials/_master.twig` includes `containers/header/_menu.twig` in `{% block header %}` and `containers/footer/_footer.twig` in `{% block footer %}`.

### JavaScript Hooks (`js/src/menu.ts` from `bolt-theme-init`)

| Hook | Element | Behaviour |
| :--- | :--- | :--- |
| `[data-sticky-header]` | `<header id="site-header">` | Height subtracted from anchor scroll targets (`auto-scroll.ts`) |
| `[data-dropdown-toggle="<id>"]` → `#<id>.dropdown` | Submenu button and panel (`components/nav/dropdown.twig`) | Accordion: click / ArrowDown opens, Escape / a press outside closes, `aria-expanded` and `inert` kept in sync, height animated via `.dropdown` |
| `[data-menu-toggle]` | `#menu-toggle` button; `data-label-open` / `data-label-close` hold the translated `aria-label`s | Opens the drawer |
| `[data-mobile-menu="drawer"]` | `<aside id="mobile-drawer" role="dialog" aria-modal="true">` (starts `inert`, `aria-hidden="true"`, `translate-x-full`) — a modal dialog for screen readers, matching the focus trap | Slide-in drawer with focus trap and body scroll lock |
| `[data-menu-backdrop]` | `#menu-backdrop` | Shown with the drawer; a click closes it |
| `[data-menu-close]` | `#menu-close` and the drawer links | Close the drawer (links also close it automatically) |
| `[data-cookie-settings]` | Footer "Nastavení cookies" button | Opens the consent settings, second layer of the banner (`bolt-cookie-consent`) |

For a height-animated panel below the header bar instead of a drawer, use `data-mobile-menu="collapse"` on the panel (see `bolt-theme-init`, section 3D).

### Translation Keys
The containers use these keys; `examples/translations.cs.xlf` and `examples/translations.en.xlf` hold their Czech and English texts. Merge them into every catalog:
```bash
php vendor/tomvondracek/bolt-skills/scripts/merge-xliff.php \
    vendor/tomvondracek/bolt-skills/skills/bolt-menu/examples/translations.cs.xlf translations/messages.cs.xlf
```
`nav.main_label`, `nav.open_menu`, `nav.close_menu`, `nav.mobile_label`, `nav.menu`, `footer.socials`, `footer.rights`, `footer.privacy`, `footer.cookie_settings`, `footer.credit`.

### 1. Smart Container: `containers/header/_menu.twig`
The smart container retrieves data using `menu_array('main')`, applies business rules (CTA split, homepage-link guard by route `homepage` / `homepage_locale`, active state compared through `locale_link()` so it also works on `/en/…` pages), and renders the header with the desktop navigation and the mobile drawer:

```twig
{# public/theme/<theme>/containers/header/_menu.twig #}
{#
  Smart Container: Header Navigation
  Retrieves menu data via `menu_array('main')` from `config/bolt/menu.yaml`.
  Splits call-to-action buttons from standard nav items, handles active states,
  and delegates rendering to pure components.

  JavaScript hooks (js/src/menu.ts from bolt-theme-init):
    [data-sticky-header]          header height subtracted from anchor scrolling (auto-scroll.ts)
    [data-dropdown-toggle]        submenu accordions (components/nav/dropdown.twig)
    [data-menu-toggle]            opens the mobile drawer
    [data-mobile-menu="drawer"]   the drawer; [data-menu-backdrop] its backdrop
    [data-menu-close]             close button (links inside the drawer close it too)

  Translation keys: nav.main_label, nav.open_menu, nav.close_menu, nav.mobile_label, nav.menu
#}

{% set current_path = app.request.pathinfo %}
{# The homepage routes are 'homepage' (/) and 'homepage_locale' (/{_locale}/). #}
{% set on_homepage = app.request.attributes.get('_route') in ['homepage', 'homepage_locale'] %}

{# 1. Retrieve all items for 'main' menu #}
{% set raw_items = menu_array('main')|default([]) %}

{# 2. Separate CTAs from regular nav links #}
{% set cta_items = raw_items|filter(i => i.class is defined and 'cta' in i.class|split(' ')) %}
{% set nav_items = raw_items|filter(i => i.class is not defined or 'cta' not in i.class|split(' ')) %}

{# 3. Optional guard: drop the homepage link ("Úvod", link: /) when already on the homepage #}
{% set nav_items = nav_items|filter(i => not (on_homepage and i.link|default('') == '/')) %}

<header id="site-header" data-sticky-header class="sticky top-0 z-40 bg-canvas/95 backdrop-blur-md border-b border-stroke">
    <div class="wrapper px-edge flex items-center justify-between h-header gap-6">

        {# Logo #}
        <a href="{{ locale_link('/') }}" class="flex items-center shrink-0" aria-label="{{ config.get('general/sitename') }}">
            {% include 'components/brand/logo.twig' ignore missing with { class: 'h-8 w-auto' } %}
        </a>

        {# Desktop Navigation #}
        <nav class="hidden menu:flex items-center" aria-label="{{ __('nav.main_label') }}">
            <ul class="flex items-center gap-1 list-none m-0 p-0">
                {% for item in nav_items %}
                    {# Compare the locale-prefixed URL with the request path, so items are also
                       active on /en/… pages; anchors (/#section) are never "active". #}
                    {% set item_url = locale_link(item.uri|default(item.link|default('/'))) %}
                    {% set is_active = item_url == current_path
                        or (item_url != locale_link('/') and current_path starts with item_url ~ '/') %}

                    {% if item.submenu is defined and item.submenu|length > 0 %}
                        {% set child_active = item.submenu|filter(s => locale_link(s.uri|default(s.link|default('/'))) == current_path)|length > 0 %}
                        {% include 'components/nav/dropdown.twig' with {
                            id: 'menu-dropdown-' ~ loop.index,
                            label: item.label,
                            submenu: item.submenu,
                            is_active: is_active or child_active
                        } %}
                    {% else %}
                        <li>
                            {% include 'components/nav/item.twig' with {
                                label: item.label,
                                uri: item.uri|default(item.link),
                                is_active: is_active,
                                is_cta: false
                            } %}
                        </li>
                    {% endif %}
                {% endfor %}
            </ul>
        </nav>

        {# Desktop Action Area (Locale Switcher + CTA buttons) #}
        <div class="hidden menu:flex items-center gap-4">
            {% include 'partials/_locale-switcher.twig' ignore missing with { mobile: false } %}

            {% for cta in cta_items %}
                {% include 'components/nav/item.twig' with {
                    label: cta.label,
                    uri: cta.uri|default(cta.link),
                    is_cta: true
                } %}
            {% endfor %}
        </div>

        {# Mobile Menu Button #}
        <button id="menu-toggle"
                type="button"
                data-menu-toggle
                aria-expanded="false"
                aria-controls="mobile-drawer"
                aria-label="{{ __('nav.open_menu') }}"
                data-label-open="{{ __('nav.open_menu') }}"
                data-label-close="{{ __('nav.close_menu') }}"
                class="menu:hidden p-2 text-ink hover:text-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent rounded-sm">
            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="size-6 shrink-0" aria-hidden="true">
                <path stroke-linecap="round" stroke-linejoin="round" d="M4 6h16M4 12h16M4 18h16"/>
            </svg>
        </button>
    </div>
</header>

{# Mobile Backdrop & Drawer — hidden from assistive tech until menu.ts opens it #}
<div id="menu-backdrop"
     data-menu-backdrop
     class="fixed inset-0 bg-night/50 z-40 opacity-0 pointer-events-none transition-opacity duration-300 menu:hidden"
     aria-hidden="true"></div>

<aside id="mobile-drawer"
       data-mobile-menu="drawer"
       role="dialog"
       aria-modal="true"
       aria-label="{{ __('nav.mobile_label') }}"
       aria-hidden="true"
       inert
       class="fixed top-0 right-0 h-full w-80 max-w-[85vw] bg-canvas z-50 flex flex-col translate-x-full transition-transform duration-300 ease-out shadow-2xl menu:hidden">
    <div class="flex items-center justify-between p-4 border-b border-stroke">
        <span class="font-bold text-lg text-ink">{{ __('nav.menu') }}</span>
        <button id="menu-close"
                type="button"
                data-menu-close
                aria-label="{{ __('nav.close_menu') }}"
                class="p-2 text-ink-2 hover:text-ink rounded-sm">
            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="size-6" aria-hidden="true">
                <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12"/>
            </svg>
        </button>
    </div>

    <nav class="flex-1 overflow-y-auto p-4 flex flex-col gap-2" aria-label="{{ __('nav.main_label') }}">
        {% for item in nav_items %}
            {% if item.submenu is defined and item.submenu|length > 0 %}
                <div class="flex flex-col gap-1 py-1">
                    <span class="font-semibold text-xs uppercase tracking-wider text-ink-3 px-3">{{ item.label }}</span>
                    {% for sub in item.submenu %}
                        <a href="{{ locale_link(sub.uri|default(sub.link)) }}"
                           data-menu-close
                           class="px-4 py-2 text-base text-ink hover:text-accent hover:bg-surface rounded-sm transition-colors">
                            {{ sub.label }}
                        </a>
                    {% endfor %}
                </div>
            {% else %}
                <a href="{{ locale_link(item.uri|default(item.link)) }}"
                   data-menu-close
                   class="px-3 py-2 text-base font-medium text-ink hover:text-accent hover:bg-surface rounded-sm transition-colors">
                    {{ item.label }}
                </a>
            {% endif %}
        {% endfor %}

        {% if cta_items|length > 0 %}
            <div class="pt-4 mt-2 border-t border-stroke flex flex-col gap-3">
                {% for cta in cta_items %}
                    <a href="{{ locale_link(cta.uri|default(cta.link)) }}"
                       data-menu-close
                       class="btn-primary text-center">
                        {{ cta.label }}
                    </a>
                {% endfor %}
            </div>
        {% endif %}

        <div class="mt-auto pt-6 border-t border-stroke">
            {% include 'partials/_locale-switcher.twig' ignore missing with { mobile: true } %}
        </div>
    </nav>
</aside>
```

### 2. Pure Component: `components/nav/item.twig`
Pure presentational component with zero database calls:

```twig
{# public/theme/<theme>/components/nav/item.twig #}
{#
  Pure Component: Navigation Link Item
  Props:
    - label (string): Display text
    - uri (string): Target link (passed to locale_link)
    - class (string|optional): Extra CSS classes
    - is_active (bool|optional): Whether item is currently active (adds aria-current="page")
    - is_cta (bool|optional): Render as the primary call-to-action button (.btn-primary)
#}
{% set target_url = locale_link(uri|default('/')) %}

{% if is_cta|default(false) %}
    <a href="{{ target_url }}"
       class="btn-primary {{ class|default('') }}">
        {{ label }}
    </a>
{% else %}
    <a href="{{ target_url }}"
       class="inline-flex items-center gap-1 px-3 py-2 font-medium text-base transition-colors duration-200 {{ is_active|default(false) ? 'text-accent font-semibold' : 'text-ink hover:text-accent' }} {{ class|default('') }}"
       {% if is_active|default(false) %}aria-current="page"{% endif %}>
        {{ label }}
    </a>
{% endif %}
```

### 3. Pure Component: `components/nav/dropdown.twig`
Accessible dropdown driven by the accordion in `menu.ts`:

```twig
{# public/theme/<theme>/components/nav/dropdown.twig #}
{#
  Pure Component: Accessible Navigation Dropdown
  Behaviour comes from js/src/menu.ts (bolt-theme-init): click or ArrowDown opens the
  panel, Escape or a press outside closes it, `aria-expanded` and `inert` stay in sync.
  The panel uses `.dropdown` (overflow: hidden; height: 0; height transition) from the
  Tailwind source; padding and borders sit on the inner element so the height animates.

  Props:
    - id (string): Unique identifier for the panel (aria-controls / data-dropdown-toggle)
    - label (string): Trigger button text
    - submenu (array): List of items with { label, uri, link }
    - is_active (bool|optional): Whether the parent or any child item is active
#}
{# Deterministic fallback id (the same on every render, so fragment caching and aria-controls work). #}
{% set dd_id = id|default('submenu-' ~ (label ~ '')|slug) %}

<li class="relative">
    <button type="button"
            data-dropdown-toggle="{{ dd_id }}"
            aria-expanded="false"
            aria-controls="{{ dd_id }}"
            class="inline-flex items-center gap-1.5 px-3 py-2 font-medium text-base cursor-pointer transition-colors duration-200 {{ is_active|default(false) ? 'text-accent font-semibold' : 'text-ink hover:text-accent' }}">
        <span>{{ label }}</span>
        <svg viewBox="0 0 24 24" class="rotate-svg size-4 shrink-0" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
            <path stroke-linecap="round" stroke-linejoin="round" d="m6 9 6 6 6-6"/>
        </svg>
    </button>

    <div id="{{ dd_id }}" class="dropdown absolute top-full left-0 min-w-52 z-50" inert>
        <ul class="mt-2 flex flex-col list-none py-2 bg-canvas border border-stroke shadow-xl rounded-sm">
            {% for sub in submenu|default([]) %}
                <li>
                    <a href="{{ locale_link(sub.uri|default(sub.link)) }}"
                       class="block px-4 py-2.5 text-sm font-normal text-ink-2 hover:text-accent hover:bg-surface transition-colors">
                        {{ sub.label }}
                    </a>
                </li>
            {% endfor %}
        </ul>
    </div>
</li>
```

### 4. Smart Container: `containers/footer/_footer.twig`
Footer columns from `menu_array('footer')`, brand column with logo, bio, phone and e-mail, social links and the legal bottom bar. Uses the dark `night` palette of `bolt-tailwind-theme`.

The bottom bar ends with the author credit („Vytvořil Tomáš Vondráček“, `footer.credit`). The portfolio it links exists in Czech and English only, so the link follows the page's language instead of the site's locale list:

| Page language | Link |
| :--- | :--- |
| `cs` (also the only language of a Czech-only site) | `https://tvondracek.cz` |
| any other (`en`, `de`, `sk`, …) | `https://tvondracek.cz/en` |

Keep the link absolute and outside `locale_link()`: that function prefixes the site's own paths, and would send a German page to `/de`, which the portfolio does not have.


```twig
{# public/theme/<theme>/containers/footer/_footer.twig #}
{#
  Smart Container: Footer Navigation & Columns
  Retrieves menu columns via `menu_array('footer')` from `config/bolt/menu.yaml`
  (top-level items are column headings, their `submenu:` lists are the links).
  Renders the brand column (logo, bio, phone, e-mail from theme.yaml), social links
  from theme.yaml, and the legal bottom bar.

  "Nastavení cookies" opens the consent settings (bolt-cookie-consent listens to
  [data-cookie-settings]); it is shown whenever theme.yaml privacy.cookies lists an item
  that needs consent (trackers, embeds) — the same rule that renders the banner.

  The operator's legal identity (name, seat, IČO, register entry, ADR body for consumer sites)
  comes from partials/_legal-identity.twig (bolt-legal-cz), on every page above the bottom bar.

  The author credit closes the bottom bar. Its link follows the page's language: the portfolio
  exists in cs and en only, so a Czech page links https://tvondracek.cz and every other
  language (en, de, sk, …) links https://tvondracek.cz/en.

  Translation keys: footer.socials, footer.rights, footer.privacy, footer.cookie_settings,
  footer.credit
#}

{% set footer_columns = menu_array('footer')|default([]) %}
{% set socials = config.get('theme/socials')|default([])|filter(url => url is not empty) %}
{# Cookie inventory from theme.yaml (bolt-cookie-consent): anything beyond `necessary` needs consent. #}
{% set has_tracking = config.get('theme/privacy/cookies')|default([])|filter(item => item.category|default('necessary') != 'necessary')|length > 0 %}

<footer class="bg-night text-night-ink-2 border-t border-night-stroke">
    <div class="wrapper px-edge py-16 flex flex-col gap-12">

        {# Top section: Brand / Bio + Link Columns #}
        <div class="flex flex-col lg:flex-row items-start justify-between gap-12">

            {# Brand summary column #}
            <div class="flex flex-col gap-4 max-w-sm">
                {% include 'components/brand/logo.twig' ignore missing with { class: 'h-8 w-auto text-night-ink', tone: 'light' } %}
                <p class="text-sm leading-relaxed">
                    {{ config.get('theme/contact/bio')|default(config.get('general/payoff')|default('')) }}
                </p>

                {# Contact quick info #}
                <div class="flex flex-col gap-1 text-sm">
                    {% if config.get('theme/contact/phone') %}
                        <a href="tel:{{ config.get('theme/contact/phone')|replace({' ': ''}) }}" class="hover:text-night-ink transition-colors">
                            {{ config.get('theme/contact/phone') }}
                        </a>
                    {% endif %}
                    {% if config.get('theme/contact/email') %}
                        <a href="mailto:{{ config.get('theme/contact/email') }}" class="hover:text-night-ink transition-colors">
                            {{ config.get('theme/contact/email') }}
                        </a>
                    {% endif %}
                </div>

                {# Social links from theme.yaml (socials: { facebook: url, … }) #}
                {% if socials|length > 0 %}
                    <ul class="flex flex-wrap items-center gap-4 pt-2" aria-label="{{ __('footer.socials') }}">
                        {% for network, url in socials %}
                            <li>
                                <a href="{{ url }}"
                                   target="_blank"
                                   rel="noopener noreferrer"
                                   class="text-xs uppercase tracking-wider hover:text-night-ink transition-colors">
                                    {{ network }}
                                </a>
                            </li>
                        {% endfor %}
                    </ul>
                {% endif %}
            </div>

            {# Footer Navigation Columns #}
            <div class="flex flex-wrap gap-10 sm:gap-16">
                {% for column in footer_columns %}
                    <div class="flex flex-col gap-4 min-w-35">
                        <h3 class="font-semibold text-sm uppercase tracking-wider text-night-ink">
                            {{ column.label }}
                        </h3>
                        <ul class="flex flex-col gap-2.5 list-none m-0 p-0 text-sm">
                            {% for item in column.submenu|default([]) %}
                                <li>
                                    <a href="{{ locale_link(item.uri|default(item.link)) }}"
                                       class="hover:text-night-ink transition-colors">
                                        {{ item.label }}
                                    </a>
                                </li>
                            {% endfor %}
                        </ul>
                    </div>
                {% endfor %}
            </div>
        </div>

        {# Legal identity: § 435 OZ data and consumer information from theme.yaml (bolt-legal-cz) #}
        {% include 'partials/_legal-identity.twig' ignore missing %}

        {# Bottom Bar: Copyright, Legal links & Author credit #}
        <div class="pt-8 border-t border-night-stroke flex flex-col sm:flex-row sm:flex-wrap items-center justify-between gap-4 text-xs text-night-ink-3">
            <p>© {{ 'now'|date('Y') }} {{ config.get('general/sitename') }}. {{ __('footer.rights') }}</p>

            <ul class="flex flex-wrap items-center gap-6 list-none m-0 p-0">
                <li>
                    <a href="{{ locale_link('/zasady-ochrany-osobnich-udaju') }}" class="hover:text-night-ink transition-colors">
                        {{ __('footer.privacy') }}
                    </a>
                </li>
                {% if has_tracking %}
                    <li>
                        <button type="button" data-cookie-settings class="hover:text-night-ink transition-colors cursor-pointer">
                            {{ __('footer.cookie_settings') }}
                        </button>
                    </li>
                {% endif %}
            </ul>

            {# Author credit: Czech pages link the Czech portfolio, every other language the English one. #}
            <p>
                {{ __('footer.credit') }}
                <a href="https://tvondracek.cz{{ app.request.locale|default('cs') == 'cs' ? '' : '/en' }}"
                   target="_blank"
                   rel="noopener"
                   class="hover:text-night-ink hover:underline transition-colors">Tomáš Vondráček</a>
            </p>
        </div>
    </div>
</footer>
```

### 5. Pure Component: `components/brand/logo.twig`
Logo image from `theme.yaml` (`logo.default`, `logo.light` for dark backgrounds), or the site name as text when no logo is configured:

```twig
{# public/theme/<theme>/components/brand/logo.twig #}
{#
  Pure Component: Brand Logo
  Renders the logo image configured in theme.yaml, or the site name as text when no
  logo is configured (useful right after scaffolding).

    # theme.yaml
    logo:
      default: 'img/logo/logo.svg'        # relative to the theme folder
      light: 'img/logo/logo-light.svg'    # variant for dark backgrounds (footer, hero)

  Props:
    - class (string|optional): Classes for the <img> / text (e.g. 'h-8 w-auto')
    - tone (string|optional): 'dark' (default, for light backgrounds) | 'light'
    - alt (string|optional): Alternative text (default: general/sitename). Pass alt: ''
        when the surrounding link already carries an aria-label.
#}
{% set sitename = config.get('general/sitename') %}
{% set src = tone|default('dark') == 'light'
    ? config.get('theme/logo/light')|default(config.get('theme/logo/default'))
    : config.get('theme/logo/default') %}

{% if src %}
    <img src="{{ asset(src) }}" alt="{{ alt is defined ? alt : sitename }}" class="{{ class|default('h-8 w-auto') }}">
{% else %}
    <span class="font-display text-lg font-semibold tracking-tight {{ class|default('') }}">{{ sitename }}</span>
{% endif %}
```

---

## Automation Scripts

### Scaffolding Script (`scripts/scaffold.sh`)
Scaffolds `config/bolt/menu.yaml` based on project archetypes:

```bash
# Auto-detect profile from ContentTypes:
bash skills/bolt-menu/scripts/scaffold.sh

# Force specific profile:
bash skills/bolt-menu/scripts/scaffold.sh --profile=landing --force
bash skills/bolt-menu/scripts/scaffold.sh --profile=catalog --force
bash skills/bolt-menu/scripts/scaffold.sh --profile=conditional --force

# Also copy Twig container and component templates into the active theme
# (header, footer, nav item, nav dropdown, brand logo; existing files are kept):
bash skills/bolt-menu/scripts/scaffold.sh --profile=catalog --templates --force
```

> [!NOTE]
> `bolt/project` ships a sample `config/bolt/menu.yaml`. Without `--force` the script stops at "already exists" **before** copying the templates, so pass `--force` on a new project (the written menu is a placeholder to be replaced with the site's IA).

### Verification Script (`scripts/verify.sh`)
Runs automated validation against Bolt CMS menu requirements:

```bash
bash skills/bolt-menu/scripts/verify.sh
```

**Checks Performed:**
1. Verifies `config/bolt/menu.yaml` exists.
2. Validates YAML syntax via `bin/console lint:yaml` and `Symfony\Component\Yaml\Yaml::parseFile`.
3. Validates mandatory `main:` menu and nested schema.
4. Checks multilingual parity: warns if a locale from `app_locales` in `config/services.yaml` is missing in a `label:` map (falls back to `locales:` in `config/bolt/config.yaml` on older projects).
5. Checks anchor formatting: errors on bare `#section` and enforces `/#section`.
6. Checks clean paths: warns if a link starts with a hardcoded prefix of one of the configured locales (`/cs/`, `/en/`, …).
7. Theme integration check: verifies `menu_array('main')` is called in the active theme, warns when `js/src/menu.ts` has no Escape handling (an opened mobile menu or dropdown cannot be closed from the keyboard), and warns on a site with another language than `cs` when the author credit links the portfolio without following the page's language.
8. Verifies all menu URLs are wrapped in `locale_link(...)`.

---

## Common Pitfalls & Solutions

| Pitfall | Symptoms | Fix |
| :--- | :--- | :--- |
| **Bare `#anchor` in `menu.yaml`** | Anchor links fail when user visits from subpages (e.g. privacy policy). | Always use leading slash: `/#kontakt` instead of `#kontakt`. |
| **Hardcoded `/en/` or `/cs/` in `link`** | Language switcher produces double prefixes (e.g. `/en/en/contact`) or breaks on default locale. | Write clean canonical paths (`/contact`). Twig's `locale_link(item.uri)` handles the prefix. |
| **Missing translation in `label` dict** | Menu item falls back to title or renders empty string in secondary locale. | Ensure every configured locale has a key: `{ cs: '...', en: '...' }`. |
| **Homepage link (`/`) shown on homepage** | Redundant "Úvod" link clutters the navbar next to the logo. | Detect the homepage by route (`app.request.attributes.get('_route') in ['homepage', 'homepage_locale']`) and filter: `nav_items\|filter(i => not (on_homepage and i.link == '/'))`. |
| **Active state compared with the unprefixed URI** | Items are never highlighted on `/en/…` pages. | Compare `locale_link(item.uri)` with `app.request.pathinfo`. |
| **`hidden group-hover:block` / `focus-within:block` on the dropdown panel** | Keyboard users cannot open the submenu (a hidden panel cannot receive focus) and `aria-expanded` never changes. | `.dropdown` panel + `data-dropdown-toggle` button driven by `menu.ts`. |
| **Drawer markup without the `data-*` hooks** | The mobile menu button does nothing. | `data-menu-toggle`, `data-mobile-menu="drawer"`, `data-menu-backdrop`, `data-menu-close` as in the header container. |
| **Colour names outside the token set** (`brand`, `ink-800`) | Undefined names generate no CSS; the header renders unstyled. | Use the tokens of `bolt-tailwind-theme` (`ink`, `ink-2`, `accent`, `surface`, `stroke`, `night*`). |
| **Using deprecated `{{ menu() }}`** | Unstyled default HTML markup from Bolt core overrides custom Tailwind classes. | Always use `menu_array('main')` and iterate using your own components. |
