Breadcrumb

Navigation trail that shows the user’s location in a hierarchy. Supports linked intermediate items, a non-clickable current item with aria-current="page", and glassy context for overlays.

Default Glassy Context

📐 Context vs. Theme

Context = Physical placement in the layout (standard page vs. glassy overlay/hero).
Theme = Site-wide user preference (light/dark mode toggle 🌙).

Below previews show each breadcrumb in both contexts. Use the 🌙 toggle (top-right) to test how breadcrumbs look in both themes. Breadcrumbs should work correctly in all 4 combinations: Light+Standard, Light+Glassy, Dark+Standard, Dark+Glassy.

1. Default Breadcrumb

Standard breadcrumb trail with linked ancestors and a non-clickable current page. Use for signed-in pages and structured admin areas.

1.1 Standard Layout Preview

Standard Context

Use on light surfaces (cards, content containers, dialogs)

1.2 Standard Layout HTML Snippet

HTML

<nav class="ui-breadcrumb" aria-label="Breadcrumb">
  <ol class="ui-breadcrumb-list">
    <li class="ui-breadcrumb-item">
      <a href="/pl/admin" class="ui-breadcrumb-link">Dashboard</a>
      <svg class="ui-breadcrumb-sep" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
      </svg>
    </li>
    <li class="ui-breadcrumb-item">
      <!-- Focus-visible demo for documentation -->
      <a href="/pl/admin/dictionaries" class="ui-breadcrumb-link is-focus-visible">Dictionaries</a>
      <svg class="ui-breadcrumb-sep" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
      </svg>
    </li>
    <li class="ui-breadcrumb-item">
      <span class="ui-breadcrumb-current" aria-current="page">User Roles</span>
    </li>
  </ol>
</nav>

1.3 Glassy Layout Preview

Glassy Context

Use on dark overlays and glass panels (signed-in shell)

1.4 Glassy Layout HTML Snippet

HTML

<nav class="ui-breadcrumb is-glassy" aria-label="Breadcrumb">
  <ol class="ui-breadcrumb-list">
    <li class="ui-breadcrumb-item">
      <a href="/pl/admin" class="ui-breadcrumb-link">Dashboard</a>
      <svg class="ui-breadcrumb-sep" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
      </svg>
    </li>
    <li class="ui-breadcrumb-item">
      <a href="/pl/admin/dictionaries" class="ui-breadcrumb-link">Dictionaries</a>
      <svg class="ui-breadcrumb-sep" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
      </svg>
    </li>
    <li class="ui-breadcrumb-item">
      <span class="ui-breadcrumb-current" aria-current="page">User Roles</span>
    </li>
  </ol>
</nav>

Usage Guidelines

✅ Do

• Use breadcrumbs for hierarchical navigation (2–6 levels)
• Keep the current page as a non-link item
• Add aria-current="page" on the current item
• Keep labels concise; allow them to wrap on narrow screens if needed
• Support non-Latin labels (PL content) without changing fonts
• Allow non-clickable intermediate items when access is limited
• Include clear separators (slash or chevron)
• Use is-glassy in glassy containers
• Ensure focus-visible outline is visible on keyboard tab
• Use is-focus-visible only to demonstrate focus in docs
• Hide the breadcrumb when there is only one item

❌ Don’t

• Don’t use breadcrumbs as primary navigation
• Don’t link the current page
• Don’t remove separators between items
• Don't exceed 8 levels on small screens
• Don’t hardcode colors or spacing
• Don’t override font sizes outside tokens
• Don’t show breadcrumbs for single-page flows
• Don’t place breadcrumbs below primary page titles
• Don’t ship is-focus-visible in production markup

⚠️ Layering Contract

Breadcrumb styles live in /assets/css/breadcrumb.css. Do not re-style breadcrumb links locally. If you need new behavior or variants, extend the Design System component instead of overriding in page CSS.

CSS Location

All breadcrumb styles are defined in:

/assets/css/breadcrumb.css

Imported by: /assets/css/ui-system.css

Includes: Base breadcrumb layout, list+item structure, focus-visible styling, glassy context colors, separator styling, icon sizing, and truncation helpers.