diff --git a/packages/breadcrumb-trail/spec/flow-api.md b/packages/breadcrumb-trail/spec/flow-api.md
new file mode 100644
index 00000000000..3ec44a91b07
--- /dev/null
+++ b/packages/breadcrumb-trail/spec/flow-api.md
@@ -0,0 +1,330 @@
+# BreadcrumbTrail Flow Developer API
+
+<!--
+Flow (Java) developer-facing API derived from requirements.md (universal + flow) and web-component-api.md. Shows the most idiomatic, minimal Java API a Flow developer would use.
+
+NOT a specification — no connector files, no @Synchronize wiring, no method bodies, no serialisation analysis.
+
+The Flow API ALWAYS wraps the web component. Every attribute/property/slot/event/CSS custom property in web-component-api.md is reachable from Java — see the Web API coverage check at the end.
+-->
+
+## 1. Displaying the ancestor trail as links
+
+Covers requirement(s): 1, 2
+
+```java
+BreadcrumbTrail breadcrumbTrail = new BreadcrumbTrail(Mode.MANUAL);
+breadcrumbTrail.add(
+        new BreadcrumbItem("Home", HomeView.class),
+        new BreadcrumbItem("Developer Guide", DeveloperGuideView.class),
+        new BreadcrumbItem("API Reference", ApiReferenceView.class),
+        new BreadcrumbItem("Authentication", AuthenticationView.class),
+        new BreadcrumbItem("OAuth2")); // last item without a path is the current page
+add(breadcrumbTrail);
+```
+
+```java
+// String-path overload for cases with no Flow route class
+breadcrumbTrail.add(
+        new BreadcrumbItem("Home", "/"),
+        new BreadcrumbItem("External", "https://example.com/docs"));
+```
+
+**Why this shape:** `BreadcrumbTrail` has an explicit `Mode` that determines who owns the trail. The nested enum `BreadcrumbTrail.Mode` has two values: `ROUTER` (default — auto-populated from Flow routing metadata, see section 8) and `MANUAL` (the application manages the items). The mode is chosen at construction — `new BreadcrumbTrail()` defaults to `ROUTER`, `new BreadcrumbTrail(Mode.MANUAL)` is explicit. Adding or removing children while in `ROUTER` mode throws `IllegalStateException`, so the two models never silently mix. In `MANUAL` mode, `BreadcrumbTrail` is a standard Flow container — it implements `HasComponentsOfType<BreadcrumbItem>` and accepts items through the inherited `add(BreadcrumbItem...)` / `addComponentAsFirst(BreadcrumbItem)` / `addComponentAtIndex(int, BreadcrumbItem)` / `remove(BreadcrumbItem...)` / `removeAll()` methods, with compile-time enforcement that only `BreadcrumbItem` instances can be added. On the web-component side the `items` JS property takes data objects, but that is a client-side concern; in Flow, items are `BreadcrumbItem` components. `BreadcrumbItem` offers the same constructor overloads as `SideNavItem`: `(label)` for the current page (no path), `(label, String path)` for hand-managed paths, `(label, Class<? extends Component> view)` as the type-safe primary form required by `DESIGN_GUIDELINES.md` "Integrate with Flow Router", and `(label, Class<? extends Component> view, RouteParameters routeParameters)` for parameterised routes. Each path-taking overload also has a prefix-component variant ending in `Component prefixComponent` (see section 4). The "current" distinction needs no extra API — an item without a path is the current item, matching the web component's declarative convention.
+
+---
+
+## 2. Optionally omitting the current page
+
+Covers requirement(s): 3
+
+```java
+// All items linkable — no current-page item included in the trail
+BreadcrumbTrail breadcrumbTrail = new BreadcrumbTrail(Mode.MANUAL);
+breadcrumbTrail.add(
+        new BreadcrumbItem("Home", HomeView.class),
+        new BreadcrumbItem("Developer Guide", DeveloperGuideView.class),
+        new BreadcrumbItem("API Reference", ApiReferenceView.class));
+```
+
+**Why this shape:** No dedicated API. When every added item has a path, no current-page indicator appears — the application simply decides whether to include a final no-path item. The Flow API inherits this from the web component's declarative convention, keeping the wrapper thin.
+
+---
+
+## 3. Overflow collapse and expansion
+
+Covers requirement(s): 6, 7
+
+```java
+BreadcrumbTrail breadcrumbTrail = new BreadcrumbTrail(Mode.MANUAL);
+breadcrumbTrail.add(
+        new BreadcrumbItem("Home", HomeView.class),
+        new BreadcrumbItem("Documents", DocumentsView.class),
+        new BreadcrumbItem("Projects", ProjectsView.class),
+        new BreadcrumbItem("2026", YearView.class, new RouteParameters("year", "2026")),
+        new BreadcrumbItem("Q1", QuarterView.class, new RouteParameters("quarter", "q1")),
+        new BreadcrumbItem("Reports", ReportsView.class),
+        new BreadcrumbItem("Summary"));
+
+// Localise the overflow button's accessible label
+breadcrumbTrail.setI18n(new BreadcrumbTrailI18n().setMoreItems("Show hidden items"));
+```
+
+**Why this shape:** Overflow collapse and the expansion menu opened by the overflow indicator (req 7) are handled entirely inside the web component — the collapsed items reappear as menu rows sourced from the same `BreadcrumbItem` components the container already holds, so no Flow-side surface is needed to wire them up. The only Flow-visible concern is the overflow indicator's accessible label, localised via a nested `BreadcrumbTrailI18n` class following the `SideNavI18n` / `MenuBarI18n` convention: `Serializable`, `@JsonInclude(JsonInclude.Include.NON_NULL)`, fluent setters. Exposed via `setI18n(BreadcrumbTrailI18n)` / `getI18n()` on `BreadcrumbTrail`.
+
+---
+
+## 4. Icons alongside item text
+
+Covers requirement(s): 8
+
+```java
+// Inline with construction — one line per item
+BreadcrumbTrail breadcrumbTrail = new BreadcrumbTrail(Mode.MANUAL);
+breadcrumbTrail.add(
+        new BreadcrumbItem("Home", HomeView.class, new Icon(VaadinIcon.HOME)),
+        new BreadcrumbItem("Documents", DocumentsView.class, new Icon(VaadinIcon.FOLDER)),
+        new BreadcrumbItem("Report.pdf"));
+```
+
+```java
+// Or set the prefix after construction
+BreadcrumbItem home = new BreadcrumbItem("Home", HomeView.class);
+home.setPrefixComponent(new Icon(VaadinIcon.HOME));
+```
+
+**Why this shape:** `BreadcrumbItem` implements `HasPrefix` from `vaadin-flow-components-base`, giving every item `setPrefixComponent` / `getPrefixComponent`. In addition, each path-taking constructor has a prefix-component variant — `(label, String path, Component prefix)`, `(label, Class<? extends Component> view, Component prefix)`, `(label, Class<? extends Component> view, RouteParameters params, Component prefix)` — matching `SideNavItem` exactly so the icon-with-path case (by far the common one) reads as a single line. The web component uses `slot="prefix"` on `<vaadin-breadcrumb-item>` and mirroring that through `HasPrefix` reuses the surface Flow developers already know. web-component-api.md explicitly does not support icons via the programmatic `items` property; Flow sidesteps that limitation because its programmatic API is component-based (`add(BreadcrumbItem...)`), not a data-object array, so icons work the same way whether the prefix is passed through a constructor or assigned via `setPrefixComponent` after construction.
+
+---
+
+## 5. Dynamic trail updates
+
+Covers requirement(s): 9
+
+```java
+// Imperative form — rebuild the trail when the browsed category changes
+BreadcrumbTrail breadcrumbTrail = new BreadcrumbTrail(Mode.MANUAL);
+breadcrumbTrail.add(
+        new BreadcrumbItem("Home", HomeView.class),
+        new BreadcrumbItem("Electronics", CategoryView.class, new RouteParameters("slug", "electronics")),
+        new BreadcrumbItem("Laptops", CategoryView.class, new RouteParameters("slug", "laptops")),
+        new BreadcrumbItem("Gaming"));
+
+categorySelector.addValueChangeListener(event -> {
+    Category category = event.getValue();
+    breadcrumbTrail.removeAll();
+    breadcrumbTrail.add(
+            new BreadcrumbItem("Home", HomeView.class),
+            new BreadcrumbItem(category.getName(), CategoryView.class,
+                    new RouteParameters("slug", category.getSlug())),
+            new BreadcrumbItem(category.getChild().getName()));
+});
+```
+
+```java
+// Reactive form — run an effect that rebuilds the children when a signal changes
+ValueSignal<Category> current = new ValueSignal<>(initialCategory);
+
+BreadcrumbTrail breadcrumbTrail = new BreadcrumbTrail(Mode.MANUAL);
+Signal.effect(breadcrumbTrail, () -> {
+    Category category = current.get();
+    breadcrumbTrail.removeAll();
+    breadcrumbTrail.add(
+            new BreadcrumbItem("Home", HomeView.class),
+            new BreadcrumbItem(category.getName(), CategoryView.class,
+                    new RouteParameters("slug", category.getSlug())),
+            new BreadcrumbItem(category.getChild().getName()));
+});
+
+// Any code that updates the signal flows through to the breadcrumb
+current.set(nextCategory);
+```
+
+**Why this shape:** In `Mode.MANUAL`, imperative updates use the standard component-tree primitives `add(...)`, `remove(...)`, `removeAll()` inherited from `HasComponentsOfType<BreadcrumbItem>` — the same API a Flow developer uses for any container, with the generic parameter ensuring only `BreadcrumbItem` instances can be passed. Reactive updates use `Signal.effect(component, Runnable)`, Flow core's primitive for running a callback whenever the observed signals change; the effect is the right granularity here because the trail is rebuilt as a tree operation (`removeAll` + `add`), not a single property set. This avoids inventing a component-specific `bindItems` surface when the generic effect primitive already covers the case. The web component itself accepts only `<vaadin-breadcrumb-item>` light-DOM children (no parallel `items` data-array property — see web-component-api.md §6), so the Flow wrapper has nothing else to map.
+
+---
+
+## 6. Navigation landmark
+
+Covers requirement(s): 10
+
+```java
+BreadcrumbTrail breadcrumbTrail = new BreadcrumbTrail(Mode.MANUAL);
+breadcrumbTrail.setAriaLabel("Product navigation");
+breadcrumbTrail.add(
+        new BreadcrumbItem("Home", HomeView.class),
+        new BreadcrumbItem("Products", ProductsView.class),
+        new BreadcrumbItem("Laptops"));
+```
+
+**Why this shape:** `BreadcrumbTrail` implements `HasAriaLabel` from Flow core — the standard Vaadin way to expose an accessible name. The web component already renders itself as a `<nav>` landmark automatically (see web-component-api.md §7), so the only Flow-facing API is the label. No component-specific default label is provided (confirmed in requirements.md Discussion).
+
+---
+
+## 7. Current page announced as current
+
+Covers requirement(s): 11
+
+```java
+// No Flow API needed — the last item without a path is automatically
+// the current page, and the web component applies aria-current="page" to it.
+breadcrumbTrail.add(
+        new BreadcrumbItem("Home", HomeView.class),
+        new BreadcrumbItem("Docs", DocsView.class),
+        new BreadcrumbItem("OAuth2")); // aria-current="page" applied automatically
+```
+
+**Why this shape:** Requirement 11 is satisfied entirely by the web component's built-in behaviour (see web-component-api.md §8): the last no-path item receives `aria-current="page"` without developer action. Introducing a Flow-side `setCurrent(...)` API would duplicate the "no path means current" convention established in requirement 1 and the web component API, violating the no-bloat principle.
+
+---
+
+## 8. Default trail derived from the router hierarchy
+
+Covers requirement(s): 13
+
+```java
+@Route("")
+@PageTitle("Home")
+public class HomeView extends Div { ... }
+
+@Route("customers")
+@PageTitle("Customers")
+public class CustomersView extends Div { ... }
+
+@Route("customers/archive")
+@PageTitle("Archive")
+public class ArchiveView extends Div {
+    public ArchiveView() {
+        // Zero configuration: router mode is the default, populates from routing metadata.
+        add(new BreadcrumbTrail());
+        // Renders as: Home › Customers › Archive
+    }
+}
+```
+
+**Why this shape:** A `BreadcrumbTrail` constructed with the default (`Mode.ROUTER`) populates itself from static route metadata. `@PageTitle` supplies each item's label and `@RouteParent` (or URL-prefix walking, see section 10) supplies the hierarchy — so auto-population never instantiates ancestor views. For the current (instantiated) view, `HasDynamicTitle` is honoured so a dynamic self-label works without further configuration. Data-dependent ancestor labels (e.g. "Acme Corp" for a specific customer) are out of scope for auto-population — applications that need them switch the trail to `Mode.MANUAL` and build it themselves (section 9). This is a Flow-only behaviour; the web component itself remains router-agnostic.
+
+---
+
+## 9. Opting out of automatic trail population
+
+Covers requirement(s): 14
+
+```java
+// Explicitly declare manual ownership in the constructor, then add items.
+BreadcrumbTrail breadcrumbTrail = new BreadcrumbTrail(Mode.MANUAL);
+breadcrumbTrail.add(
+        new BreadcrumbItem("Catalog", CatalogView.class),
+        new BreadcrumbItem(category.getName()));
+```
+
+```java
+// Async loading — MANUAL mode leaves the trail empty until the data arrives,
+// so the router-derived default never flashes in.
+BreadcrumbTrail breadcrumbTrail = new BreadcrumbTrail(Mode.MANUAL);
+loadCategoryAsync(category -> breadcrumbTrail.add(buildTrail(category)));
+```
+
+```java
+// Switch mode after construction if the intent changes later.
+breadcrumbTrail.setMode(Mode.MANUAL);
+BreadcrumbTrail.Mode current = breadcrumbTrail.getMode();
+```
+
+```java
+// In ROUTER mode, calling add(...) is a programming error.
+BreadcrumbTrail routerTrail = new BreadcrumbTrail(); // defaults to Mode.ROUTER
+routerTrail.add(new BreadcrumbItem("Home", HomeView.class));
+// → throws IllegalStateException: BreadcrumbTrail is in Mode.ROUTER;
+//   switch to Mode.MANUAL before adding items.
+```
+
+**Why this shape:** `BreadcrumbTrail.Mode` with values `ROUTER` (default) and `MANUAL` makes the two configuration styles explicit. The application picks one at construction (`new BreadcrumbTrail(Mode.MANUAL)`) or via `setMode(Mode)` at any time; `getMode()` reads the current value. Children can only be added or removed while in `Mode.MANUAL` — calling `add`, `remove`, or `removeAll` while in `Mode.ROUTER` throws `IllegalStateException`, so the two models never silently mix. `MANUAL` mode also keeps the trail empty until the application populates it, which covers the asynchronous-loading scenario without requiring a placeholder child: the router-derived default simply does not run.
+
+---
+
+## 10. Route-parent annotation overrides URL-based parent lookup
+
+Covers requirement(s): 15
+
+```java
+@Route("orders/edit/:orderId")
+@RouteParent(OrdersView.class)
+@PageTitle("Edit Order")
+public class EditOrderView extends Div { ... }
+```
+
+```java
+// Renders as: Home › Orders › Edit Order
+// (instead of Home › Orders › Edit › Edit Order implied by the URL segments)
+```
+
+**Why this shape:** A class-level annotation `@RouteParent(Class<? extends Component>)` declares a view's parent in the application's route hierarchy, overriding URL-prefix walking. It is deliberately named in route-hierarchy terms rather than breadcrumb-specific terms — the relationship it expresses ("this route's conceptual parent is that route") is independent of breadcrumb rendering and can be consumed by any navigation component that needs to traverse the hierarchy. An annotation (vs a method on a new interface) is the right shape for this because the information is static and known at compile time — mirroring how `@Route`, `@RouteAlias`, and `@PageTitle` are themselves annotations. Walking continues from the declared parent using the same rules, so chains of `@RouteParent` compose naturally. The annotation lives alongside the other Flow route metadata on the view class.
+
+---
+
+## Web API coverage check
+
+| Web API surface (from web-component-api.md) | Flow API | Notes |
+|---|---|---|
+| `<vaadin-breadcrumb-trail>` element | `new BreadcrumbTrail()` | constructor; `HasSize`, `HasStyle`, `HasAriaLabel`, `HasComponentsOfType<BreadcrumbItem>` |
+| `<vaadin-breadcrumb-item>` child | `HasComponentsOfType<BreadcrumbItem>#add(BreadcrumbItem...)`, `addComponentAsFirst(BreadcrumbItem)`, `addComponentAtIndex(int, BreadcrumbItem)`, `remove(BreadcrumbItem...)`, `removeAll()` | standard component-tree management, typed to `BreadcrumbItem` at compile time; no component-specific `setItems`/`addItem` |
+| `path` attribute on item | `BreadcrumbItem#setPath(String)` / `setPath(Class<? extends Component>)` / `setPath(Class, RouteParameters)` / constructor overloads | type-safe primary form per `DESIGN_GUIDELINES.md` "Integrate with Flow Router" |
+| last-item-without-path → current item | implicit — construct with `new BreadcrumbItem(String label)` (no path) | no dedicated current flag |
+| `aria-current="page"` on current item | — (set automatically by the web component) | no Flow API needed |
+| `slot="prefix"` on item | `BreadcrumbItem implements HasPrefix` → `setPrefixComponent(Component)` | shared mixin from `vaadin-flow-components-base` |
+| Programmatic items data array | — (no such property on the web component, see web-component-api.md §6) | not applicable; Flow manages items as a tree of `BreadcrumbItem` components via `HasComponentsOfType<BreadcrumbItem>` |
+| `i18n` JS property | `BreadcrumbTrail#setI18n(BreadcrumbTrailI18n)` / `getI18n()` | nested class; `Serializable`, `@JsonInclude(NON_NULL)`, fluent setters |
+| `i18n.moreItems` | `BreadcrumbTrailI18n#setMoreItems(String)` / `getMoreItems()` | overflow button accessible label |
+| `<nav>` landmark rendering | — (automatic in web component) | no Flow API needed |
+| `aria-label` on the host | `BreadcrumbTrail implements HasAriaLabel` | `setAriaLabel(String)` / `getAriaLabel()` from Flow core |
+| `--vaadin-breadcrumb-trail-separator` CSS custom property | `BreadcrumbTrail#getStyle().set("--vaadin-breadcrumb-trail-separator", ...)` via `HasStyle` | per `DESIGN_GUIDELINES.md` "Styling lives in CSS, not Java" — no dedicated Java setter |
+| RTL separator flipping | — (handled in CSS when `dir="rtl"`) | inherited from the application / `HasStyle` |
+| Flow: auto-populate from router | `BreadcrumbTrail.Mode` enum (`ROUTER`, `MANUAL`); `new BreadcrumbTrail()` / `new BreadcrumbTrail(Mode)`; `setMode(Mode)` / `getMode()` | default `ROUTER`; `add`/`remove`/`removeAll` throw `IllegalStateException` while in `ROUTER` mode |
+| Flow: route-parent override | `@RouteParent(Class<? extends Component>)` | class-level annotation on `@Route` views |
+
+## Discussion
+
+**Q: Why add prefix-component overloads to the `BreadcrumbItem` constructors?**
+
+Icons are the primary real-world use of the prefix slot (home icon on the root, folder icon on category items), and calling `setPrefixComponent(...)` on a separate line after construction is noticeably more verbose than the idiomatic Flow form for other components. `SideNavItem` — the closest convention anchor — already exposes the same prefix-component overloads, so BreadcrumbTrail matching them keeps the two components consistent and lets the most common declaration (icon + label + route) fit on one line. `setPrefixComponent` remains available for the case where the prefix is determined after construction (e.g. dynamic icon based on data), so the convenience overloads do not reduce flexibility.
+
+**Q: Why an explicit `Mode` enum instead of inferring ownership from whether children were added?**
+
+Earlier iterations of this design relied on an internal "no children at attach = auto-populate" heuristic. That works for the happy path but becomes ambiguous in edge cases: re-attach after `removeAll`, children added in `BeforeEnter` vs. in the constructor, async loading, tests that move the component. An explicit `Mode` enum removes the ambiguity — the application declares its intent at construction (or via `setMode`), and the component enforces the contract. Calling `add`, `remove`, or `removeAll` while in `Mode.ROUTER` throws `IllegalStateException` rather than silently discarding the call or mixing the two models, so the footgun turns into a clear failure at the point of misuse. A boolean `setAutoPopulate(boolean)` was considered but rejected because "automatic" does not name the *source* of the items; `ROUTER` makes the meaning explicit and leaves room for other modes (e.g. a future `PROVIDER` mode tied to a deferred `BreadcrumbProvider`) without a breaking name change.
+
+**Q: How is requirement 16 (data-driven trails that depend on runtime data) covered without a dedicated API?**
+
+It is covered by manual construction: the application loads the data it needs in the view and calls `add(...)` / `removeAll()` (section 5 and section 9) to build the trail. Every dynamic case — the customer-name example, per-user conditional items, trails derived from domain state — can be expressed this way using the standard component-tree APIs. For reactive updates, `Signal.effect(breadcrumbTrail, ...)` rebuilds the children whenever observed signals change. A dedicated declarative mechanism (for example a `BreadcrumbTrailProvider` that receives a `BreadcrumbTrailContext` describing the current navigation, and returns the full trail so that the breadcrumb recomputes itself on each route change) was designed out through several iterations and ultimately excluded from this first version. The reasons: the manual-construction path already works end-to-end; a good provider API carries non-trivial surface (a context type, lookup helpers for static metadata, rules for when the provider runs, per-instance vs. application-wide scope) that is hard to get right without real application feedback; and once introduced the provider shape is hard to evolve. A provider API remains a likely future addition once usage patterns are known — this version intentionally keeps the surface small.
+
+**Q: Why is there no section for the separator (reqs 4, 5, 12)?**
+
+Separator presence (req 4), customisation (req 5), and RTL flipping (req 12) are all handled entirely by the web component and the theme — there is no Flow-specific Java API to demonstrate. Per `DESIGN_GUIDELINES.md` "Styling lives in CSS, not Java", visual customisations like the separator icon are exposed as CSS custom properties on the host, not as Java setters: applications use `HasStyle#getStyle().set("--vaadin-breadcrumb-trail-separator", ...)` or a theme stylesheet. A dedicated "here's how to call `getStyle()`" section would duplicate generic Flow knowledge without adding BreadcrumbTrail-specific value, so these requirements are documented solely in the Web API coverage table (the `--vaadin-breadcrumb-trail-separator` row and the RTL row).
+
+**Q: Why no click listener on `BreadcrumbItem`?**
+
+Items render as plain anchors (`<a href>`) under the hood. With `setPath(Class<? extends Component>)`, Flow's router intercepts the click and navigates without full page reload. With `setPath(String)`, the browser follows the href. Neither path requires a Flow-level listener, and adding one would invite developers to implement navigation twice (once as a listener, once as a route). `SideNavItem` follows the same philosophy — no `addClickListener`.
+
+**Q: Why no theme variants?**
+
+web-component-api.md does not expose any theme variants for BreadcrumbTrail — the component has a single canonical appearance with theme-layer differences only (Lumo vs Aura). No `BreadcrumbTrailVariant` enum is added because there is nothing for it to contain. One can be introduced later if variants emerge.
+
+**Q: Why use `HasComponentsOfType<BreadcrumbItem>` rather than a bespoke `setItems(BreadcrumbItem...)` / `addItem(BreadcrumbItem...)` API?**
+
+A breadcrumb is a container of items — in Flow terms, a component that holds child components. Expressing that through the standard `HasComponentsOfType<T>` interface from Flow core keeps the API consistent with every other typed Flow container, gives developers `add`, `addComponentAsFirst`, `addComponentAtIndex`, `remove`, and `removeAll` for free, and avoids inventing yet another bespoke item-collection surface. The generic parameter `BreadcrumbItem` gives compile-time enforcement that only `BreadcrumbItem` instances can be added, so developers get type safety without the component needing to reject foreign children at runtime. The web component itself only accepts `<vaadin-breadcrumb-item>` light-DOM children (no parallel data-array `items` property), so the Flow wrapper's component-tree model is a one-to-one fit.
+
+**Q: Why no dedicated `bindItems(Signal<...>)` method?**
+
+Flow core's `Signal.effect(component, Runnable)` already provides the primitive for reactive child-tree updates: the effect re-runs whenever observed signals change, and inside it the application calls `removeAll()` + `add(...)` to rebuild the trail. A component-specific `bindItems` would wrap that primitive in a convenience, but at the cost of an extra API surface, a `SignalBinding<List<BreadcrumbItem>>` return type, its own `BindingActiveException` lifecycle, and questions about how it composes with direct `add` calls. Keeping the reactive story on `Signal.effect` reuses an API developers already know and leaves the door open to introduce a sugar method later if real usage shows it is worth the surface.
+
+**Q: What happens if `@RouteParent` forms a cycle or points at a class without `@Route`?**
+
+These are implementation concerns the spec (`create-component-flow-spec`) will resolve — the expected behaviour is that cycles are detected and truncated, and a parent class without `@Route` is treated as if the annotation were absent (fall back to URL-prefix walking). The API surface here is only the annotation itself; the resolution algorithm belongs to the specification.
+
+**Q: Why `@RouteParent` rather than a breadcrumb-specific name?**
+
+The annotation expresses a route-hierarchy relationship — "the conceptual parent of this route is that route" — which is not inherently tied to breadcrumb rendering. Naming it `@RouteParent` (vs. `@BreadcrumbTrailParent` or `@BreadcrumbTrailRouteParent`) keeps the declaration reusable: any future navigation component that needs to walk the route hierarchy (e.g. a back-navigation helper, an SEO link-graph generator, a parent-link utility) can consume the same annotation without the name implying it belongs to BreadcrumbTrail alone. The `@Route*` prefix also groups it naturally with the existing routing annotations (`@Route`, `@RouteAlias`) in Flow core, so developers find it where they look for route metadata. This avoids coupling application-level hierarchy metadata to a specific presentation component — the view author declares a routing fact, not a breadcrumb hint.
+
+**Q: Why is `BreadcrumbTrailI18n` a class rather than a single setter for `moreItems`?**
+
+Only one translatable string exists today, but the nested-class shape follows `SideNavI18n` and `MenuBarI18n` so that future accessibility strings (for example an announcement when the trail updates, or per-item aria-label fallback text) can be added without a breaking API change. Keeping the JSON-backed i18n object convention consistent across Vaadin Flow components also lets Vaadin's i18n tooling treat them uniformly.
diff --git a/packages/breadcrumb-trail/spec/flow-spec.md b/packages/breadcrumb-trail/spec/flow-spec.md
new file mode 100644
index 00000000000..e24b7718fb6
--- /dev/null
+++ b/packages/breadcrumb-trail/spec/flow-spec.md
@@ -0,0 +1,691 @@
+# BreadcrumbTrail Flow Component Specification
+
+> Wraps the experimental web component `<vaadin-breadcrumb-trail>`. Flow users enable it via the `com.vaadin.experimental.breadcrumbTrailComponent` feature flag — defined by a `BreadcrumbTrailFeatureFlagProvider` registered in this module (no Flow core change needed). The flag key matches the `window.Vaadin.featureFlags.breadcrumbTrailComponent` flag on the web-component side, so a single entry in `vaadin-featureflags.properties` controls both sides.
+
+## Key Design Decisions
+
+1. **`Mode` enum drives ownership.** Following flow-api.md §1 and §9, `BreadcrumbTrail.Mode` is a public nested enum with values `ROUTER` (default) and `MANUAL`. The mode is set at construction (`new BreadcrumbTrail()` / `new BreadcrumbTrail(Mode)`) and can be switched at runtime via `setMode(Mode)`. `add`/`remove`/`removeAll` throw `IllegalStateException` while in `Mode.ROUTER`. `setMode(Mode)` is symmetric: both transitions clear the current children and install the new mode's wiring — `ROUTER → MANUAL` drops router-derived items and unregisters the navigation listener, `MANUAL → ROUTER` drops manually-added items and starts the router listener plus an initial rebuild. See "Mode switching" below for the full contract.
+
+2. **`HasComponentsOfType<BreadcrumbItem>` for child management.** Per flow-api.md §1 "Why this shape". Implemented by the type-parameterised children interface from Flow core ([PR #24186](https://github.com/vaadin/flow/pull/24186)). The interface extends `HasElement, HasEnabled` and supplies — as default methods — `add(T...)`, `add(Collection<T>)`, `remove(T...)`, `remove(Collection<T>)`, `removeAll()`, `addComponentAtIndex(int, T)`, `addComponentAsFirst(T)`, `replace(T, T)`, and `bindChildren(Signal<List<S>>, SerializableFunction<S, T>)`. All of these are available on `BreadcrumbTrail` without the component re-implementing them, and all of them must be intercepted by the `Mode.ROUTER` guard (see KDD §1). `HasEnabled` is inherited transitively — it does not need to appear in `BreadcrumbTrail`'s `implements` list.
+
+3. **Router integration via `AfterNavigationListener`.** For `Mode.ROUTER`, the component registers `UI.addAfterNavigationListener(...)` in its attach handler and unregisters in detach. The listener walks the route hierarchy — `@RouteParent` first, then URL-prefix — and calls `updateChildrenInternal(List<BreadcrumbItem>)` to replace the trail. `updateChildrenInternal` sets an internal `boolean routerUpdateInProgress` flag, routes the update through the normal component API (`removeAll()` + `add(...)`), then clears the flag; the `Mode.ROUTER` guard on the public methods skips the throw when the flag is set. This means router-derived items are regular child components — `getChildren()` returns them, serialisation captures them, and the Flow virtual-children mechanism is not involved.
+
+4. **`@RouteParent` annotation lives in Flow core.** Per flow-api.md §10. `com.vaadin.flow.router.RouteParent` is introduced in Flow core alongside `@Route`, `@RouteAlias`, `@ParentLayout`. The breadcrumb module only consumes it — it neither defines it nor re-exports it. See "Reuse and Proposed Adjustments" for the Flow core dependency.
+
+5. **Route-hierarchy walking is a Flow core feature, not a breadcrumb-specific resolver.** The "given a route class, walk up via `@RouteParent` then URL-prefix fallback" algorithm is useful to any navigation component (back-button helpers, SEO link-graph generators, sitemap renderers), so it lives in Flow core next to `@RouteParent` itself. The breadcrumb consumes it via a public helper — see "Reuse and Proposed Adjustments → Flow core: route-hierarchy walker". The resolver reads only static metadata (`@PageTitle`, `@RouteParent`) and therefore never instantiates ancestor views; the breadcrumb adds the dynamic-title step for the current (already-instantiated) view itself.
+
+6. **No connector needed.** All state is set via standard Element attributes/properties from server-side Java — `setPath` writes the `path` attribute, `setPrefixComponent` uses `SlotUtils.setSlot` for the prefix slot, `setI18n` pushes a JSON object to the `i18n` client property. The web component's overflow behaviour is entirely client-side, and the web component itself only accepts `<vaadin-breadcrumb-item>` light-DOM children (no programmatic `items` data-array property — see web-component-api.md §6 and its Discussion). No connector file under `src/main/resources/META-INF/resources/frontend/`.
+
+7. **No events.** Neither `BreadcrumbTrail` nor `BreadcrumbItem` exposes a server-side event (no click listeners, no navigate events — see flow-api.md Discussion "Why no click listener on `BreadcrumbItem`?"). Items render as anchors and the Flow router intercepts clicks at the document level.
+
+8. **No `@Synchronize`'d properties.** No client-driven state round-trips to the server. `has-overflow` is a visual state attribute the server does not need to observe.
+
+9. **No theme variants.** Per flow-api.md Discussion "Why no theme variants?" — no `BreadcrumbTrailVariant` enum.
+
+10. **`BreadcrumbTrailI18n` is a nested static class.** Follows the `SideNavI18n` / `MenuBarI18n` convention — `Serializable`, `@JsonInclude(JsonInclude.Include.NON_NULL)`, fluent setters returning `BreadcrumbTrailI18n`. Serialised with `JacksonUtils.beanToJson` and pushed to the client via `getElement().setPropertyJson("i18n", ...)` in the attach handler (so re-attach re-sets the property for the fresh client-side element).
+
+11. **Package name `com.vaadin.flow.component.breadcrumbtrail`.** Mirrors `com.vaadin.flow.component.sidenav` — the short form that drops internal hyphens.
+
+12. **Module `vaadin-breadcrumb-trail-flow-parent`.** Standard parent-child split `vaadin-{name}-flow-parent` / `vaadin-{name}-flow` / `vaadin-{name}-flow-integration-tests` / `vaadin-{name}-testbench`.
+
+13. **Serialisation.** The `AfterNavigationListener` `Registration` returned from the attach handler is held as a `transient` field and rebuilt in the attach handler on re-attach (Flow may replace the client-side element). `BreadcrumbTrailI18n` implements `Serializable`. `Mode` enum is inherently serialisable. No other non-trivial state.
+
+---
+
+## Module / Package Layout
+
+```
+flow-components/
+└── vaadin-breadcrumb-trail-flow-parent/
+    ├── pom.xml
+    ├── vaadin-breadcrumb-trail-flow/
+    │   ├── pom.xml
+    │   └── src/
+    │       ├── main/java/com/vaadin/flow/component/breadcrumbtrail/
+    │       │   ├── BreadcrumbTrail.java                # host element, Mode enum, BreadcrumbTrailI18n nested class
+    │       │   ├── BreadcrumbItem.java                 # <vaadin-breadcrumb-item>
+    │       │   ├── BreadcrumbTrailFeatureFlagProvider.java  # defines the Feature constant
+    │       │   └── ExperimentalFeatureException.java   # local exception with a helpful message
+    │       ├── main/resources/
+    │       │   └── META-INF/services/
+    │       │       └── com.vaadin.experimental.FeatureFlagProvider   # one-line ServiceLoader registration
+    │       └── test/java/com/vaadin/flow/component/breadcrumbtrail/tests/
+    │           ├── BreadcrumbTrailTest.java
+    │           ├── BreadcrumbTrailModeTest.java
+    │           ├── BreadcrumbItemTest.java
+    │           ├── BreadcrumbTrailSerializableTest.java
+    │           ├── BreadcrumbTrailI18nTest.java
+    │           └── FeatureFlagTest.java
+    ├── vaadin-breadcrumb-trail-flow-integration-tests/
+    │   ├── pom.xml
+    │   └── src/
+    │       ├── main/java/com/vaadin/flow/component/breadcrumbtrail/tests/
+    │       │   ├── ManualBreadcrumbTrailPage.java     # @Route for Mode.MANUAL
+    │       │   ├── RouterBreadcrumbTrailPage.java     # @Route for Mode.ROUTER
+    │       │   ├── RouteParentPage.java               # @Route with @RouteParent
+    │       │   ├── DynamicTitlePage.java              # HasDynamicTitle on current view
+    │       │   └── IconBreadcrumbTrailPage.java       # prefix icons
+    │       └── test/java/com/vaadin/flow/component/breadcrumbtrail/tests/
+    │           ├── ManualBreadcrumbTrailIT.java
+    │           ├── RouterBreadcrumbTrailIT.java
+    │           ├── RouteParentIT.java
+    │           └── IconBreadcrumbTrailIT.java
+    └── vaadin-breadcrumb-trail-testbench/
+        ├── pom.xml
+        └── src/main/java/com/vaadin/flow/component/breadcrumbtrail/testbench/
+            ├── BreadcrumbTrailElement.java            # @Element("vaadin-breadcrumb-trail")
+            └── BreadcrumbItemElement.java             # @Element("vaadin-breadcrumb-item")
+```
+
+Java package: `com.vaadin.flow.component.breadcrumbtrail`.
+
+Integration-tests module must include `src/main/resources/vaadin-featureflags.properties` enabling `com.vaadin.experimental.breadcrumbTrailComponent=true`, mirroring `vaadin-master-detail-layout-flow-integration-tests`.
+
+---
+
+## Component Classes
+
+### `BreadcrumbTrail` — container
+
+```java
+@Tag("vaadin-breadcrumb-trail")
+@NpmPackage(value = "@vaadin/breadcrumb-trail", version = "25.2.0-alpha{N}")
+@JsModule("@vaadin/breadcrumb-trail/src/vaadin-breadcrumb-trail.js")
+public class BreadcrumbTrail extends Component
+        implements HasSize, HasStyle, HasAriaLabel,
+                   HasComponentsOfType<BreadcrumbItem> {
+
+    public enum Mode {
+        ROUTER,
+        MANUAL
+    }
+
+    // State
+    private Mode mode;
+    private BreadcrumbTrailI18n i18n;
+    private transient Registration navigationRegistration;
+
+    // Constructors
+    public BreadcrumbTrail();                       // defaults to Mode.ROUTER
+    public BreadcrumbTrail(Mode mode);
+
+    // Mode
+    public Mode getMode();
+    public void setMode(Mode mode);                 // switching resets the internal state
+
+    // Items — all inherited from HasComponentsOfType<BreadcrumbItem>, each
+    // overridden to throw IllegalStateException if Mode.ROUTER (unless the
+    // internal routerUpdateInProgress flag is set — see KDD §3):
+    //   add(BreadcrumbItem...) / add(Collection<BreadcrumbItem>)
+    //   addComponentAsFirst(BreadcrumbItem)
+    //   addComponentAtIndex(int, BreadcrumbItem)
+    //   remove(BreadcrumbItem...) / remove(Collection<BreadcrumbItem>)
+    //   removeAll()
+    //   replace(BreadcrumbItem, BreadcrumbItem)
+    //   bindChildren(Signal<List<S>>, SerializableFunction<S, BreadcrumbItem>)
+    //
+    // getChildren() / children stream — always allowed.
+
+    // i18n
+    public BreadcrumbTrailI18n getI18n();
+    public void setI18n(BreadcrumbTrailI18n i18n);
+
+    // Accessible name — inherited from HasAriaLabel:
+    //   setAriaLabel(String)
+    //   getAriaLabel()
+
+    // Lifecycle
+    @Override
+    protected void onAttach(AttachEvent attachEvent);   // checks feature flag; re-pushes i18n; wires router listener if ROUTER
+    @Override
+    protected void onDetach(DetachEvent detachEvent);   // unregisters router listener
+
+    // Nested i18n class — see §i18n below
+    public static class BreadcrumbTrailI18n implements Serializable { ... }
+}
+```
+
+**Implemented mixin interfaces:**
+
+- `HasSize` — covers requirement that the component can be sized by the application (universal API hygiene).
+- `HasStyle` — required for requirement 5 (customise separator via `--vaadin-breadcrumb-trail-separator` CSS custom property) and for `getStyle()` access per `DESIGN_GUIDELINES.md` "Styling lives in CSS, not Java".
+- `HasAriaLabel` — requirement 10 (navigation landmark accessible name). Flow core interface.
+- `HasComponentsOfType<BreadcrumbItem>` — requirement 1, 9 (add/remove/manage items with compile-time type safety). Flow core interface. All inherited mutating methods — `add(T...)` / `add(Collection<T>)` / `remove(T...)` / `remove(Collection<T>)` / `removeAll()` / `addComponentAsFirst(T)` / `addComponentAtIndex(int, T)` / `replace(T, T)` / `bindChildren(Signal<List<S>>, SerializableFunction<S, T>)` — are overridden to throw `IllegalStateException` when `Mode.ROUTER` (unless the internal `routerUpdateInProgress` flag is set).
+
+**@Synchronize'd properties:** none.
+
+**Events:** none.
+
+**Feature-flag check.** `onAttach` calls `BreadcrumbTrail.checkFeatureFlag(attachEvent.getUI())` following the pattern from `MasterDetailLayout.checkFeatureFlag`: throws `ExperimentalFeatureException` when `FeatureFlags.BREADCRUMB_TRAIL_COMPONENT` is disabled.
+
+**Router mode wiring (attach).** The component relies on Flow's existing router and router-utils API; no new per-call mechanism is invented. Two entry points feed the resolver:
+
+- `UI.addAfterNavigationListener(AfterNavigationListener)` — public API on `UI`. The listener receives an `AfterNavigationEvent` whose `getLocation()`, `getActiveChain()`, and `getRouteParameters()` are all public accessors. This catches every navigation for the lifetime of the attachment (including long-lived shell placement).
+- An initial, synchronous rebuild in `onAttach` itself, for the case where the breadcrumb is added to a view that has already finished rendering (so no navigation is pending and the listener has nothing to fire on). Flow core does not currently expose a public "read current navigation state" API at arbitrary times — `UI.getInternals().getActiveViewLocation()` and `UI.getInternals().getActiveRouterTargetsChain()` are the de facto accessors (public methods, but on `UIInternals` which sits in `com.vaadin.flow.component.internal`). See "Reuse and Proposed Adjustments → Flow core dependencies" for the proposal to promote these to a public `Router`/`RouteUtil` entry point.
+
+```java
+protected void onAttach(AttachEvent attachEvent) {
+    super.onAttach(attachEvent);
+    checkFeatureFlag(attachEvent.getUI());
+
+    if (mode == Mode.ROUTER) {
+        UI ui = attachEvent.getUI();
+        navigationRegistration = ui.addAfterNavigationListener(this::rebuildFromRouter);
+
+        // Initial population: read current navigation state from the UI.
+        // Today this goes through UIInternals; see the Proposed Adjustments
+        // section for the preferred public-API landing.
+        UIInternals internals = ui.getInternals();
+        rebuildFromRouter(internals.getActiveViewLocation(),
+                          internals.getActiveRouterTargetsChain(),
+                          RouteConfiguration.forRegistry(
+                                  ComponentUtil.getRouter(this).getRegistry()));
+    }
+}
+```
+
+`rebuildFromRouter` has two overloads that normalise on the same private builder:
+
+```java
+// Overload 1 — AfterNavigationEvent-driven (ongoing navigations)
+void rebuildFromRouter(AfterNavigationEvent event);
+
+// Overload 2 — direct state (initial attach)
+void rebuildFromRouter(Location currentLocation,
+                      List<HasElement> activeChain,
+                      RouteConfiguration routeConfiguration);
+```
+
+Both overloads ultimately build the trail via the same private routine (see "How `BreadcrumbTrail` builds the trail" below), which calls the Flow core `RouteHierarchy` walker, wraps the returned ancestor classes into `BreadcrumbItem` instances, and hands the result to `updateChildrenInternal(trail)`. Both guard against stale callbacks: `if (!isAttached()) return;` first.
+
+`updateChildrenInternal(List<BreadcrumbItem> trail)`:
+
+```java
+private boolean routerUpdateInProgress;
+
+void updateChildrenInternal(List<BreadcrumbItem> trail) {
+    routerUpdateInProgress = true;
+    try {
+        removeAll();                                  // reaches super.removeAll() via HasComponentsOfType
+        add(trail.toArray(BreadcrumbItem[]::new));    // reaches super.add(T...)
+    } finally {
+        routerUpdateInProgress = false;
+    }
+}
+```
+
+The public `add` / `addComponentAsFirst` / `addComponentAtIndex` / `remove` / `removeAll` / `replace` / `bindChildren` overrides check `mode == Mode.ROUTER && !routerUpdateInProgress` and throw `IllegalStateException` if so. This means router-derived items are regular logical children — `getChildren()` returns them, serialisation captures them, no virtual-children machinery is involved.
+
+**Mode switching.** `setMode(Mode newMode)`:
+- If already equal, no-op.
+- On transition `ROUTER → MANUAL`: clear any router-derived items via `updateChildrenInternal(List.of())`, unregister the navigation listener. Subsequent `add(...)` calls are the application's responsibility.
+- On transition `MANUAL → ROUTER`: clear any manually-added items via `updateChildrenInternal(List.of())` (same bypass — the children are replaced by the router-derived trail anyway). Register the navigation listener if attached and trigger an initial `rebuildFromRouter`; if not attached, registration happens in the next `onAttach`.
+
+---
+
+### `BreadcrumbItem` — child element
+
+```java
+@Tag("vaadin-breadcrumb-item")
+@NpmPackage(value = "@vaadin/breadcrumb-trail", version = "25.2.0-alpha{N}")
+@JsModule("@vaadin/breadcrumb-trail/src/vaadin-breadcrumb-item.js")
+public class BreadcrumbItem extends Component
+        implements HasText, HasEnabled, HasPrefix, HasTooltip {
+
+    // Constructors — mirror SideNavItem's overload set
+    public BreadcrumbItem(String text);                                                            // current page (no path)
+    public BreadcrumbItem(String text, String path);
+    public BreadcrumbItem(String text, Class<? extends Component> view);
+    public BreadcrumbItem(String text, Class<? extends Component> view, RouteParameters params);
+    public BreadcrumbItem(String text, String path, Component prefixComponent);
+    public BreadcrumbItem(String text, Class<? extends Component> view, Component prefixComponent);
+    public BreadcrumbItem(String text, Class<? extends Component> view,
+                          RouteParameters params, Component prefixComponent);
+
+    // Text — inherited from HasText:
+    //   setText(String)
+    //   getText()
+    //   bindText(Signal<String>) — returns SignalBinding<String>
+
+    // Path
+    public String getPath();
+    public void setPath(String path);
+    public void setPath(Class<? extends Component> view);
+    public void setPath(Class<? extends Component> view, RouteParameters parameters);
+
+    // Prefix — inherited from HasPrefix:
+    //   setPrefixComponent(Component)
+    //   getPrefixComponent()
+
+    // Tooltip — inherited from HasTooltip:
+    //   setTooltipText(String)
+    //   getTooltip()
+}
+```
+
+**Implemented mixin interfaces:**
+
+- `HasText` — the default slot of `<vaadin-breadcrumb-item>` holds the item's text content. `HasText` from Flow core provides `setText(String)` / `getText()` and `bindText(Signal<String>) → SignalBinding<String>` as default methods, so the signal-binding entry point for reactive item text is also available without additional code.
+- `HasEnabled` — lets the application disable individual items (e.g. an ancestor the user has no permission to visit).
+- `HasPrefix` — requirement 8 (icons). `slot="prefix"` on `<vaadin-breadcrumb-item>`, shared mixin from `vaadin-flow-components-base`.
+- `HasTooltip` — useful for long labels that may not fit. Shared mixin.
+
+**No `HasSuffix`** — web-component-api.md explicitly excludes it. If added later on the web-component side, the Flow class adds `HasSuffix` to the `implements` clause; that is strictly additive.
+
+**No click listener** — flow-api.md Discussion "Why no click listener on `BreadcrumbItem`?" The web component renders an anchor; the Flow router intercepts clicks.
+
+**Path resolution.** `setPath(Class<? extends Component>)` and `setPath(Class, RouteParameters)` mirror `SideNavItem.setPath(...)` exactly: `RouteConfiguration.forRegistry(ComponentUtil.getRouter(this).getRegistry()).getUrl(view, params)` and the resulting string is written to the `path` attribute. Router-agnosticism: Flow wraps the routing resolution, but the anchor `<a href="...">` is still plain HTML — Flow does not intercept clicks at the component level.
+
+**No @Synchronize'd properties.** `path` is server-driven.
+
+**Events:** none.
+
+---
+
+## i18n
+
+```java
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public static class BreadcrumbTrailI18n implements Serializable {
+    private String moreItems;
+
+    public String getMoreItems();
+    public BreadcrumbTrailI18n setMoreItems(String moreItems);
+}
+```
+
+Exposed on `BreadcrumbTrail` via `setI18n(BreadcrumbTrailI18n)` / `getI18n()`. Serialised via `JacksonUtils.beanToJson(i18n)` and pushed to the client through `getElement().setPropertyJson("i18n", json)` inside the attach handler (so that on re-attach the fresh client element receives the property again). Null `i18n` results in the property not being set, letting the web component's default take over.
+
+| Field | Type | Default (English) | Web-component `i18n` field | Notes |
+|---|---|---|---|---|
+| `moreItems` | String | `null` (web component default: `""`) | `moreItems` | `aria-label` of the overflow button (see web-component-api.md §4) |
+
+Setter returns `this` so calls can be chained: `new BreadcrumbTrailI18n().setMoreItems("Show hidden items")`.
+
+---
+
+## Theme Variants
+
+Not applicable. No `BreadcrumbTrailVariant` enum is introduced. See flow-api.md Discussion "Why no theme variants?"
+
+---
+
+## Connector
+
+**No connector required.** All state is set via Element attributes and properties directly from server-side Java:
+
+- `path` — `setAttribute("path", ...)` on `BreadcrumbItem`
+- `prefix` slot — managed by `HasPrefix` / `SlotUtils.setSlot(this, "prefix", component)`
+- `i18n` — `setPropertyJson("i18n", JacksonUtils.beanToJson(i18n))` on `BreadcrumbTrail`
+- `aria-label` — `HasAriaLabel` attribute
+- Item set — light-DOM children (component tree), observed client-side by `SlotController`
+
+No JavaScript file under `src/main/resources/META-INF/resources/frontend/`.
+
+---
+
+## Feature Flag
+
+The component is experimental and the Flow wrapper is gated by a feature flag defined locally in this module — mirroring the convention used by `Badge`, `Slider`, and the other experimental components in flow-components. No Flow core change is needed.
+
+### `BreadcrumbTrailFeatureFlagProvider`
+
+```java
+package com.vaadin.flow.component.breadcrumbtrail;
+
+import java.util.List;
+
+import com.vaadin.experimental.Feature;
+import com.vaadin.experimental.FeatureFlagProvider;
+
+public class BreadcrumbTrailFeatureFlagProvider implements FeatureFlagProvider {
+
+    public static final Feature BREADCRUMB_TRAIL_COMPONENT = new Feature(
+            "Breadcrumb Trail component",                                   // title
+            "breadcrumbTrailComponent",                                     // id — matches web-component flag
+            "https://github.com/vaadin/platform/issues/{platform-issue-id}", // tracking issue
+            true,                                                           // requiresServerRestart
+            "com.vaadin.flow.component.breadcrumbtrail.BreadcrumbTrail");   // primary class owning the flag
+
+    @Override
+    public List<Feature> getFeatures() {
+        return List.of(BREADCRUMB_TRAIL_COMPONENT);
+    }
+}
+```
+
+### ServiceLoader registration
+
+File: `src/main/resources/META-INF/services/com.vaadin.experimental.FeatureFlagProvider`
+
+```
+com.vaadin.flow.component.breadcrumbtrail.BreadcrumbTrailFeatureFlagProvider
+```
+
+Flow's `FeatureFlags` discovers the provider via the standard `java.util.ServiceLoader` mechanism at startup. No build-time code generation.
+
+### `ExperimentalFeatureException`
+
+```java
+package com.vaadin.flow.component.breadcrumbtrail;
+
+public class ExperimentalFeatureException extends RuntimeException {
+    public ExperimentalFeatureException() {
+        super("""
+                The Breadcrumb Trail component is currently an experimental feature \
+                and needs to be explicitly enabled. The component can be \
+                enabled using Copilot, in the experimental features tab, \
+                or by adding a \
+                `src/main/resources/vaadin-featureflags.properties` file \
+                with the following content: \
+                `com.vaadin.experimental.breadcrumbTrailComponent=true`""");
+    }
+}
+```
+
+### Attach-time check
+
+`BreadcrumbTrail.onAttach` calls a private `checkFeatureFlag(UI)` that follows the `Badge` / `Slider` / `MasterDetailLayout` pattern exactly:
+
+```java
+private void checkFeatureFlag(UI ui) {
+    FeatureFlags featureFlags = FeatureFlags
+            .get(ui.getSession().getService().getContext());
+    if (!featureFlags.isEnabled(
+            BreadcrumbTrailFeatureFlagProvider.BREADCRUMB_TRAIL_COMPONENT)) {
+        throw new ExperimentalFeatureException();
+    }
+}
+```
+
+Integration-tests module enables the flag at startup with `src/main/resources/vaadin-featureflags.properties` containing `com.vaadin.experimental.breadcrumbTrailComponent=true`. Unit tests use the `@EnableFeatureFlagExtension` JUnit 6 extension or the equivalent fixture used by other experimental-component tests.
+
+---
+
+## `@RouteParent` Annotation
+
+`com.vaadin.flow.router.RouteParent` is introduced in Flow core (see "Reuse and Proposed Adjustments → Flow core dependencies"). The breadcrumb module only reads it — it does not redefine or re-export it.
+
+Expected shape in Flow core:
+
+```java
+package com.vaadin.flow.router;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface RouteParent {
+    /**
+     * The view class that is the conceptual parent of the annotated
+     * {@link Route @Route} class.
+     *
+     * The parent class should itself be annotated with {@code @Route}. If
+     * it is not, consumers of this annotation (e.g. the breadcrumb
+     * resolver) fall back to URL-prefix walking for this step.
+     */
+    Class<? extends Component> value();
+}
+```
+
+The annotation is consumed by a Flow core helper (see "Reuse and Proposed Adjustments → Flow core: route-hierarchy walker") — not by breadcrumb-specific code — so any navigation component can use it.
+
+### How `BreadcrumbTrail` builds the trail
+
+The breadcrumb does no walking of its own. On each navigation it:
+
+1. Identifies the current route class and the current view instance from `AfterNavigationEvent#getActiveChain()`.
+2. Calls the Flow core walker to get the ancestor chain: `List<Class<? extends Component>> chain = RouteHierarchy.resolveAncestors(currentRoute, routeConfiguration);` (root-first, inclusive of `currentRoute` as the last entry — see the walker's contract in "Reuse and Proposed Adjustments").
+3. For each ancestor class in `chain` except the last, reads its `@PageTitle` and resolves its URL via `RouteConfiguration#getUrl(ancestorClass, RouteParameters.empty())`, producing `new BreadcrumbItem(title, ancestorClass)`.
+4. For the last entry (the current route): uses `HasDynamicTitle#getPageTitle()` on the current view instance if it implements the interface, otherwise reads `@PageTitle` on the class. Constructs `new BreadcrumbItem(title)` with no path — the current item is the non-link.
+5. Calls `updateChildrenInternal(trail)`.
+
+Everything the breadcrumb contributes — the dynamic-title step for the current view, the wrapping into `BreadcrumbItem` components, the `Mode.ROUTER` guard bypass — is breadcrumb-specific. The hierarchy walking, cycle detection, and `@RouteParent`-versus-URL-prefix fallback live in Flow core.
+
+**Flow APIs used directly by the breadcrumb (all public):**
+
+| Purpose | API call |
+|---|---|
+| Current active chain at navigation time | `AfterNavigationEvent#getActiveChain()` |
+| Current route params at navigation time | `AfterNavigationEvent#getRouteParameters()` |
+| Current location at navigation time | `AfterNavigationEvent#getLocation()` |
+| Resolve `Class<? extends Component>` → URL | `RouteConfiguration#getUrl(Class, RouteParameters)` |
+| Obtain the registry-scoped config | `RouteConfiguration.forRegistry(ComponentUtil.getRouter(this).getRegistry())` |
+| Read the current view's dynamic title | `HasDynamicTitle#getPageTitle()` on the view instance |
+| Read a route class's static title | `routeClass.getAnnotation(PageTitle.class).value()` |
+| Walk the route hierarchy | Flow core walker (see Reuse) |
+
+**Route parameters on ancestors:** the breadcrumb resolves ancestor URLs with `RouteParameters.empty()`, because ancestor routes may have a different parameter set from the current route. Applications that need ancestor labels with live data should use `Mode.MANUAL` and build the trail themselves (flow-api.md §9).
+
+---
+
+## TestBench Elements
+
+### `BreadcrumbTrailElement`
+
+```java
+@Element("vaadin-breadcrumb-trail")
+public class BreadcrumbTrailElement extends TestBenchElement {
+
+    public List<BreadcrumbItemElement> getItems();
+
+    public BreadcrumbItemElement getCurrentItem();          // the item with the `current` state attribute (last no-path)
+
+    public BreadcrumbItemElement getItemByText(String text);
+
+    public BreadcrumbItemElement getItemByPath(String path);
+
+    public boolean hasOverflow();                           // reads has-overflow attribute
+
+    public TestBenchElement getOverflowButton();            // shadow-DOM part="overflow-button"
+
+    public void openOverflowOverlay();                       // click overflow button
+
+    public TestBenchElement getOverflowOverlay();           // the <vaadin-breadcrumb-trail-overlay> element
+
+    public List<TestBenchElement> getOverflowItems();       // links inside the open overlay
+}
+```
+
+### `BreadcrumbItemElement`
+
+```java
+@Element("vaadin-breadcrumb-item")
+public class BreadcrumbItemElement extends TestBenchElement {
+
+    public String getText();
+
+    public String getPath();
+
+    public boolean isCurrent();                             // reads `current` state attribute
+
+    public boolean hasPrefix();                             // reads `has-prefix` state attribute
+
+    public TestBenchElement getPrefixSlotContent();
+
+    @Override
+    public void click();                                    // clicks the anchor in shadow DOM
+}
+```
+
+Queries use the same pattern as `SideNavElement` / `SideNavItemElement`: `$("vaadin-breadcrumb-item").all()` for items, shadow-DOM CSS for parts and slotted content.
+
+---
+
+## Reuse and Proposed Adjustments to Existing Modules
+
+### Flow core: a `Signal<NavigationState>` for the current route — Proposed
+
+The resolver's initial-attach path needs to read the active location and active router-targets chain without a pending `AfterNavigationEvent`. Today this goes through `UIInternals.getActiveViewLocation()` and `UIInternals.getActiveRouterTargetsChain()` — both public methods on a type that sits in `com.vaadin.flow.component.internal`. The `internal` package suffix signals "not part of the stable public API".
+
+Rather than promote these two accessors to a public facade, the preferred landing is a **reactive signal** exposing the UI's current navigation state:
+
+```java
+// in com.vaadin.flow.router.Router (or on UI directly):
+public Signal<NavigationState> getCurrentNavigation();
+
+// where NavigationState carries the same data the resolver needs:
+public record NavigationState(
+        Class<? extends Component> routeClass,
+        Component viewInstance,                // for HasDynamicTitle
+        RouteParameters routeParameters,
+        Location location) {}
+
+// finer-grained variants, so consumers rerun only on relevant changes:
+public Signal<Class<? extends Component>> getCurrentRoute();
+public Signal<RouteParameters>            getCurrentRouteParameters();
+public Signal<Location>                   getCurrentLocation();
+```
+
+With this primitive in place, the breadcrumb's router mode collapses to a single subscription:
+
+```java
+Signal.effect(breadcrumbTrail,
+        () -> updateChildrenInternal(resolveTrail(Router.getCurrent().getCurrentNavigation().get())));
+```
+
+What falls away compared to the current listener-based design:
+
+- **No `addAfterNavigationListener` / `Registration` lifecycle** — `Signal.effect(component, Runnable)` is already bound to the component's attach/detach; auto-unsubscribes on detach, re-subscribes on re-attach.
+- **No `transient navigationRegistration` field** — signals handle lifecycle.
+- **No stale-callback guard** — signal subscriptions stop delivering as soon as the component detaches.
+- **No split between "initial state" and "subsequent events"** — `Signal#get()` always returns current truth, so the "what if the component attaches after the navigation already fired" edge case just works.
+- **No `UIInternals` dependency anywhere in the breadcrumb** — the signal is the public, documented accessor for current navigation state.
+
+The signal composes beyond breadcrumbs: SideNav's current-item highlighting (today client-side URL matching) could become a server-side `Signal.computed(...)` over `getCurrentLocation`; a back-button's visibility could bind to whether `getCurrentRoute().get()` carries a `@RouteParent`; analytics hooks and page-title manipulators each become one-liners. `AfterNavigationListener` stays — the signal is a reactive overlay, not a replacement for the event API.
+
+Until the signal ships, the resolver calls `UIInternals` directly and accepts the compatibility risk. Those accessors have been stable across many Vaadin releases, and any flow-components code depending on them would need to migrate in the same release as the signal lands anyway.
+
+Affects: Flow core. Fits the broader direction of making Flow state reactive-first (alongside `ValueSignal`, `Signal.effect`, `HasComponentsOfType.bindChildren`).
+
+### Flow core: route-hierarchy walker — Proposed
+
+`@RouteParent` is generic routing metadata, so the code that reads it and walks the route hierarchy is generic too. Rather than ship breadcrumb-specific resolver logic that any future navigation component would have to duplicate, the walker lands in Flow core alongside `@RouteParent`.
+
+Expected shape (names indicative; exact placement is a Flow-core decision):
+
+```java
+// in com.vaadin.flow.router
+public final class RouteHierarchy {
+
+    /**
+     * Returns the chain of route classes from the root down to and
+     * including {@code routeClass}, using {@code @RouteParent} when
+     * present and falling back to URL-prefix walking otherwise. Cycles
+     * are detected and truncated.
+     *
+     * @return a root-first list; the last element is always
+     *         {@code routeClass} when it is routable.
+     */
+    public static List<Class<? extends Component>> resolveAncestors(
+            Class<? extends Component> routeClass,
+            RouteConfiguration routeConfiguration);
+
+    /**
+     * Returns the immediate parent of {@code routeClass}, or empty if
+     * no parent can be resolved. Reads {@code @RouteParent} first, then
+     * URL-prefix walks.
+     */
+    public static Optional<Class<? extends Component>> resolveParent(
+            Class<? extends Component> routeClass,
+            RouteConfiguration routeConfiguration);
+}
+```
+
+**Algorithm contract** (implemented in Flow core; the breadcrumb only consumes it):
+
+1. Start with `routeClass`; if it has no `@Route` annotation, return an empty list (no hierarchy to walk).
+2. Maintain `Set<Class<? extends Component>> visited`, initialised with `routeClass`.
+3. At each step: read `@RouteParent` from the current class. If present and its value has `@Route`, jump there. Otherwise (annotation absent, or target is not a `@Route`), strip the last `/`-separated segment from the current class's URL (resolved via `RouteConfiguration#getUrl`) and call `RouteConfiguration#getRoute(strippedUrl)`; use that as the parent if present.
+4. Terminate when no parent is found, when the candidate is already in `visited` (cycle), or when URL-prefix stripping produces an empty URL.
+5. Return the list root-first, inclusive of the original `routeClass` as the last element.
+
+This is additive to Flow core — one new class next to `@RouteParent`, no change to existing router API. Tests for the walker (including cycle handling and parent-without-`@Route` fallback) live with Flow core, not with the breadcrumb module.
+
+Affects: Flow core. The breadcrumb depends on it for `Mode.ROUTER` but adds no code of its own for hierarchy walking.
+
+### `com.vaadin.flow.router.RouteParent` — Flow core dependency
+
+`@RouteParent` is not tied to breadcrumb rendering — per flow-api.md Discussion "Why `@RouteParent` rather than a breadcrumb-specific name?", the annotation belongs in `com.vaadin.flow.router` alongside `@Route`, `@RouteAlias`, `@ParentLayout`. This lets any future navigation component (back-helpers, parent-link renderers, SEO link-graph utilities) consume the same declaration.
+
+The annotation will land in Flow core and this module depends on it. Ensure `flow-components-bom` targets a Flow version that includes the `RouteParent` annotation.
+
+Affects: no flow-components module defines this annotation; the breadcrumb module imports `com.vaadin.flow.router.RouteParent` indirectly through the Flow core `RouteHierarchy` walker.
+
+### `HasComponentsOfType<T>` in Flow core — Dependency
+
+The Flow wrapper uses `com.vaadin.flow.component.HasComponentsOfType<BreadcrumbItem>` from Flow core ([PR #24186](https://github.com/vaadin/flow/pull/24186)). The interface extends `HasElement, HasEnabled` and provides the full child-management surface as default methods — `add(T...)`, `add(Collection<T>)`, `remove(T...)`, `remove(Collection<T>)`, `removeAll()`, `addComponentAtIndex(int, T)`, `addComponentAsFirst(T)`, `replace(T, T)`, and `bindChildren(Signal<List<S>>, SerializableFunction<S, T>)`. `BreadcrumbTrail` overrides each of these mutating methods so it can enforce the `Mode.ROUTER` guard (see KDD §3 for the `routerUpdateInProgress` bypass).
+
+Affects: `flow-components-bom` pom.xml Flow version property — ensure it is raised to the Flow version that includes PR #24186.
+
+### `vaadin-flow-components-base` — Used as-is
+
+- `HasPrefix` — prefix slot for `BreadcrumbItem`.
+- `HasTooltip` — tooltip support on `BreadcrumbItem`.
+
+No modifications.
+
+### Flow core `HasAriaLabel`, `HasEnabled`, `HasSize`, `HasStyle` — Used as-is
+
+No modifications.
+
+---
+
+## Coverage
+
+| Requirement | Addressed in spec section(s) |
+|---|---|
+| 1. Displaying the ancestor trail | Component Classes → `BreadcrumbTrail` (`HasComponentsOfType<BreadcrumbItem>`); `BreadcrumbItem` (constructors with text + path) |
+| 2. Current page indication | `BreadcrumbItem(String text)` (no path) — web component renders as non-link, applies `current` state attribute |
+| 3. Optionally omitting the current page | No API — application chooses whether to add a no-path final item |
+| 4. Visual separator between items | Web component + theme (no Flow API) |
+| 5. Customizable separator appearance | `HasStyle` → `getStyle().set("--vaadin-breadcrumb-trail-separator", ...)` |
+| 6. Overflow collapse of intermediate items | Web component (no Flow API) |
+| 7. Expanding collapsed items | Web component; `BreadcrumbTrailI18n.moreItems` sets the overflow button's `aria-label` |
+| 8. Items may display icons | `BreadcrumbItem implements HasPrefix` + constructor overloads ending in `Component prefixComponent` |
+| 9. Dynamic trail updates | `HasComponentsOfType<BreadcrumbItem>` `add`/`remove`/`removeAll` in `Mode.MANUAL`; inherited `bindChildren(Signal<List<...>>, factory)` or `Signal.effect(breadcrumbTrail, ...)` for reactive updates |
+| 10. Navigation landmark | `BreadcrumbTrail implements HasAriaLabel` |
+| 11. Current page announced as current | Web component (no Flow API) |
+| 12. Directional separator flips in RTL | Web component + theme (no Flow API) |
+| 13. Flow: Default trail derived from router | `Mode.ROUTER` (default); `onAttach` registers `AfterNavigationListener`; the Flow core `RouteHierarchy.resolveAncestors(...)` walker walks `@RouteParent` + URL prefixes; the breadcrumb adds `@PageTitle` / `HasDynamicTitle` label resolution for the returned classes |
+| 14. Flow: Opting out of automatic trail population | `Mode.MANUAL` (via constructor or `setMode`); `add`/`remove`/`removeAll` throw `IllegalStateException` in `Mode.ROUTER` |
+| 15. Flow: Sitemap parent annotation overrides URL-based parent lookup | `@RouteParent` annotation in Flow core; `RouteHierarchy.resolveAncestors` consults it before URL-prefix walking |
+| 16. Flow: Routes can dynamically supply their breadcrumb contribution | Covered via the manual-construction pattern: `Mode.MANUAL` + application-side data loading + `add(...)` (see flow-api.md Discussion "How is requirement 16 … covered without a dedicated API?"). No new Flow API in this iteration — explicitly documented as a possible future addition. |
+
+---
+
+## Discussion
+
+Questions raised during spec production, with their resolutions.
+
+**Q: How does `Mode.ROUTER` react to navigation?**
+
+`onAttach` registers `UI.addAfterNavigationListener(event -> rebuildFromRouter(...))` and holds the returned `Registration` in a transient field. `onDetach` unregisters. Each navigation rebuilds the trail by calling the Flow core `RouteHierarchy.resolveAncestors(...)` walker, wrapping each returned class into a `BreadcrumbItem`, and handing the list to an internal `updateChildrenInternal(List<BreadcrumbItem>)` that bypasses the `Mode.ROUTER` guard on `add`/`remove`/`removeAll` — user code cannot reach this path.
+
+**Q: What happens if the user calls `setMode(Mode.ROUTER)` on a trail that already has children?**
+
+`setMode` clears the trail and installs the router-derived one — no exception. Both transitions (`ROUTER → MANUAL` and `MANUAL → ROUTER`) discard the existing children and let the new mode's wiring start fresh. Earlier designs considered throwing `IllegalStateException` on `MANUAL → ROUTER` with children, forcing the caller to `removeAll()` first; that was rejected because `setMode` semantically asks "change who owns the trail", which implies the old owner's items are no longer authoritative. Making the caller call `removeAll()` adds no safety — the next line of application code does exactly that — and creates a class of boilerplate-plus-exception traps when a mode switch happens in a handler that doesn't know what state the trail is in. The symmetric auto-clear rule is simpler and matches how `setItems`-shaped APIs behave elsewhere in Flow.
+
+**Q: Is there a way to drive the trail reactively from a `Signal<List<BreadcrumbItem>>`?**
+
+Not via a dedicated `bindItems` method. Per flow-api.md Discussion "Why no dedicated `bindItems(Signal<...>)` method?", Flow core's `Signal.effect(component, Runnable)` is sufficient — the effect re-runs whenever observed signals change, and the callback does `removeAll()` + `add(...)`. This keeps the API surface small and lets the `bindItems` decision be revisited after real usage.
+
+**Q: Why `Mode` instead of a `Breadcrumb{Trail,Router}Mode` or similar prefixed enum?**
+
+Nested enum `BreadcrumbTrail.Mode` is the Vaadin convention for short enum types strongly tied to a single component (e.g. `Dialog.Position`, `Notification.Position`). Fully-qualified `BreadcrumbTrail.Mode.MANUAL` and imported `Mode.MANUAL` both read naturally.
+
+**Q: Why is there no `setTarget(String)` / `setOpenInNewBrowserTab(boolean)` on `BreadcrumbItem`?**
+
+An earlier iteration mirrored `SideNavItem` and exposed `setTarget(String)` for setting the anchor's `target` attribute (e.g. `_blank` to open in a new tab). It was removed along with the underlying web-component property. Breadcrumb items are part of a hierarchical navigation trail within the current application — opening an ancestor in a new tab is not a supported interaction and introducing API for it encourages patterns that fight the component's purpose (the user would end up with two tabs for the same hierarchy, neither reflecting the other's state). If a concrete use case emerges later, adding `setTarget` is strictly additive.
+
+**Q: Is per-item reactive text available?**
+
+Yes — `BreadcrumbItem` implements `HasText`, which provides `bindText(Signal<String>) → SignalBinding<String>` as a default method from Flow core. Applications that want per-item reactive text bind a signal to a specific item directly: `item.bindText(textSignal)`. The container-level reactive pattern (`Signal.effect` on the `BreadcrumbTrail`) remains the right choice when the whole trail's shape changes; `bindText` is for the narrower case where an item's text updates without the trail structure changing.
+
+**Q: Does the router listener need to guard against the detached-component case?**
+
+Yes — the listener is unregistered in `onDetach`, but a navigation may fire between the detach event and the registration cleanup on another thread. `rebuildFromRouter` guards with `if (!isAttached()) return;` so a stray late callback is a no-op.
+
+**Q: Why does `getI18n()` return the last-set value (or `null`) rather than lazily creating a default `BreadcrumbTrailI18n`?**
+
+For consistency with `SideNav.getI18n()`, which returns `null` until `setI18n(...)` is called. Applications that want to tweak a single field build a new instance: `trail.setI18n(new BreadcrumbTrailI18n().setMoreItems("Show hidden items"))`. A lazy-init getter would hide the fact that the i18n object is a JSON payload pushed to the client — making it feel like a reactive bean when it isn't. The current shape also lets `null` mean "use the web component's built-in defaults", which is a meaningful state the lazy-init pattern cannot express.
+
diff --git a/packages/breadcrumb-trail/spec/problem-statement.md b/packages/breadcrumb-trail/spec/problem-statement.md
new file mode 100644
index 00000000000..85b3458b5e1
--- /dev/null
+++ b/packages/breadcrumb-trail/spec/problem-statement.md
@@ -0,0 +1,59 @@
+# BreadcrumbTrail Problem Statement
+
+## Problem
+
+Users navigating hierarchically structured web applications need a way to understand their current location within the hierarchy and quickly move up to ancestor pages. This is especially important when users arrive deep in a hierarchy via search results, bookmarks, or shared links and have no context for where they are in the application's structure.
+
+## Target Users
+
+End users of business web applications with multi-level hierarchical navigation, such as:
+
+- **Content management systems** where editors navigate folders, categories, and nested content
+- **E-commerce admin panels** where operators drill into product catalogs, order details, and customer records
+- **Documentation portals** where readers browse topic hierarchies
+- **File management interfaces** where users navigate directory structures
+- **Enterprise dashboards** where analysts move between organizational units, projects, and detail views
+
+Breadcrumbs are most valuable in applications with three or more navigation levels, where the primary navigation (e.g., side nav) may not fully convey the user's current depth.
+
+## Differentiation
+
+### Side Navigation
+
+Side Navigation displays the full (or expandable) navigation tree persistently in a sidebar. It is the primary navigation mechanism. Breadcrumbs are a lightweight, secondary indicator that complements Side Nav by showing the current path inline above the page content. Breadcrumbs do NOT replace Side Nav or serve as primary navigation.
+
+### Tabs
+
+Tabs switch between peer-level content sections (horizontal siblings). Breadcrumbs show the vertical ancestor path. These are orthogonal: a page reached via tabs may still have a breadcrumb trail showing its position in the broader hierarchy.
+
+### Progress Indicator
+
+Progress indicators show position in a linear, sequential multi-step process (e.g., a checkout wizard). Breadcrumbs show position in a non-linear hierarchy. Sequential step flows are out of scope for breadcrumbs.
+
+### Browser Back Button
+
+The back button navigates through session history (temporal). Breadcrumbs navigate the information architecture (structural). Breadcrumbs should not replicate path-based history trails.
+
+## Use Cases
+
+1. **Navigating up a hierarchy.** A user is viewing a deeply nested page and wants to move up to a parent or grandparent page. The breadcrumb trail shows the full path from the root to the current page, and each ancestor is a link the user can click to jump directly to that level.
+
+   *Example: A user in a documentation portal is reading an article at "Home > Developer Guide > API Reference > Authentication > OAuth2". They click "API Reference" in the breadcrumb to jump back to the API overview page.*
+
+2. **Orienting after a deep landing.** A user arrives at a page deep in the application via a search result, a bookmarked URL, or a link shared by a colleague. They have no context for where this page sits in the application structure. The breadcrumb trail immediately communicates the page's position in the hierarchy without requiring the user to explore the navigation.
+
+   *Example: A support agent receives a link to a customer's order detail page. The breadcrumb shows "Home > Customers > Acme Corp > Orders > #10432", immediately telling them they are inside the Acme Corp customer record.*
+
+3. **Navigating a dynamic or user-driven hierarchy.** The hierarchy is not a fixed site map but is constructed from application data. The application provides the trail dynamically, and the breadcrumb reflects whatever hierarchy the application defines.
+
+   *Example: A user browses a product catalog filtered by category. The breadcrumb shows "Electronics > Laptops > Gaming" — a path derived from the data model, not a static sitemap. If they switch to browsing by brand instead, the trail changes to "Brands > Asus > Laptops".*
+
+## Discussion
+
+**Q: Should breadcrumb items support sibling navigation (dropdown menus to browse sibling pages at the same level)?**
+
+No. Breadcrumb items are plain links to ancestors only. Sibling browsing is handled by other navigation components such as Side Nav. This keeps the breadcrumb focused on its core purpose of vertical hierarchy navigation.
+
+**Q: Should the breadcrumb scope include attribute-based trails (e.g., e-commerce filter paths), or only location-based hierarchy?**
+
+The breadcrumb should support both a static hierarchy (reflecting the application's information architecture) and a dynamic hierarchy provided by the application. The component does not need to distinguish between the two -- it renders whatever trail the application supplies. This covers location-based paths, data-driven paths, and attribute-based paths alike.
diff --git a/packages/breadcrumb-trail/spec/requirements.md b/packages/breadcrumb-trail/spec/requirements.md
new file mode 100644
index 00000000000..e7fc7594d28
--- /dev/null
+++ b/packages/breadcrumb-trail/spec/requirements.md
@@ -0,0 +1,177 @@
+# BreadcrumbTrail Requirements
+
+## 1. Displaying the ancestor trail
+
+The breadcrumb displays a horizontal sequence of items representing the path from the root of a hierarchy to the user's current location. Each ancestor item is a navigable link that takes the user directly to that level when activated.
+
+*Example: A user viewing an article sees "Home > Developer Guide > API Reference > Authentication > OAuth2". Clicking "API Reference" navigates them to the API overview page.*
+
+---
+
+## 2. Current page indication
+
+The last item in the trail represents the user's current location and is visually distinct from the ancestor links. It is not an interactive link — it serves as a label confirming where the user is.
+
+*Example: In "Home > Customers > Acme Corp", the text "Acme Corp" appears in a different style (e.g., not underlined, not clickable) to show it is the current page, while "Home" and "Customers" are links.*
+
+---
+
+## 3. Optionally omitting the current page
+
+The application can choose whether the current-page item is included in the trail. When omitted, the breadcrumb shows only the ancestor links leading up to (but not including) the current page.
+
+*Example: A documentation portal shows the page title as a heading below the breadcrumb. The breadcrumb displays "Home > Developer Guide > API Reference" without repeating "Authentication" because the heading already identifies the current page.*
+
+---
+
+## 4. Visual separator between items
+
+A visual separator appears between consecutive items to convey the hierarchical relationship. The separator is purely decorative and is not announced by assistive technology.
+
+*Example: Each pair of adjacent items is separated by a forward-pointing chevron: "Home › Laptops › Gaming".*
+
+---
+
+## 5. Customizable separator appearance
+
+The application can change the visual appearance of the separator to match its design language.
+
+*Example: An application replaces the default chevron separator with a forward slash, so the trail reads "Home / Products / Laptops".*
+
+---
+
+## 6. Overflow collapse of intermediate items
+
+When the trail contains more items than fit the available horizontal width, intermediate items collapse in order of ancestry — starting from the item closest to the root — until only the root and the current item remain uncollapsed. If further collapsing is still needed, the root item finally collapses as well. The current item never collapses. Collapsed items are replaced by a single overflow indicator (such as an ellipsis button).
+
+The rationale: the root and the current item's immediate ancestors are the ones the user is most likely to want to see and navigate to, so they are preserved the longest.
+
+*Example: A file manager path "Home > Documents > Projects > 2026 > Q1 > Reports > Summary" first collapses to "Home > … > Q1 > Reports > Summary" (hiding "Documents" and "Projects"), then to "Home > … > Reports > Summary", then to "Home > … > Summary", and finally — if even that doesn't fit — to "… > Summary".*
+
+---
+
+## 7. Expanding collapsed items
+
+When items are collapsed behind the overflow indicator, the user can activate the indicator to reveal the hidden items so they can navigate to any level in the trail.
+
+*Example: The user clicks the "…" button and sees a menu listing "Documents", "Projects", "2026", "Q1", and "Reports". They click "Q1" to navigate directly to that level.*
+
+The expanded list is reachable through both keyboard models the user might bring to it: standard linear Tab navigation (so any user moving through the page with Tab encounters the hidden links the same way they encounter every other anchor) and menu-style Up/Down arrow keys (so users who recognise the visual as a menu, or who arrive at it from an in-page menu interaction, can navigate it without breaking that mental model). Pressing Escape closes the expanded list and returns focus to the overflow indicator.
+
+---
+
+## 8. Items may display icons
+
+Each breadcrumb item can optionally display an icon alongside its text label. Icons are supplementary — the text label remains the primary identifier.
+
+*Example: The root item shows a home icon next to the label "Home", while a category item shows a folder icon next to "Documents".*
+
+---
+
+## 9. Dynamic trail updates
+
+The breadcrumb trail can be updated at runtime to reflect a hierarchy that changes based on application state, user navigation, or data-driven paths. The component renders whatever trail the application provides, without assuming a fixed sitemap.
+
+*Example: A product catalog breadcrumb shows "Electronics > Laptops > Gaming" when browsing by category. When the user switches to browsing by brand, the application updates the trail to "Brands > Asus > Laptops", and the breadcrumb immediately reflects the new path.*
+
+---
+
+## 10. Navigation landmark
+
+The breadcrumb identifies itself as a navigation landmark so that assistive technology users can locate it among other landmarks on the page.
+
+*Example: A screen reader user pressing a landmark shortcut finds the breadcrumb navigation region without having to read through every link on the page.*
+
+---
+
+## 11. Current page announced as current by assistive technology
+
+When the current-page item is included in the trail, assistive technology announces it as the current page, distinguishing it from the ancestor links.
+
+*Example: A screen reader user tabbing through the breadcrumb hears each ancestor announced as a link. The last item is announced as "OAuth2, current page", making clear that this is their current location rather than a navigable link.*
+
+---
+
+## 12. Directional separator flips in right-to-left layouts
+
+When the component renders in a right-to-left context, directional separators (such as chevrons) flip to point in the reading direction, maintaining the visual indication of hierarchy from right to left.
+
+*Example: In an Arabic-language application, the breadcrumb reads from right to left and the chevron separators point left instead of right, so the visual flow matches the reading direction.*
+
+---
+
+## 13. Flow: Default trail derived from the router hierarchy
+
+In the Flow wrapper, instantiating a breadcrumb without configuring its items causes it to populate itself automatically from the application's router. The default strategy walks up the URL path of the current route and matches each prefix to a registered Flow route, producing one breadcrumb item per matched ancestor. The text shown for each item is the matched route's view title (the value Flow uses to set the page title for that route — typically the route's `@PageTitle`, or the title supplied dynamically by the view).
+
+*Example: A user navigates to `/customers/acme/orders`. The orders view is annotated `@PageTitle("Orders")`, the customer detail view dynamically sets its title to "Acme Corp", the customers list view is `@PageTitle("Customers")`, and the root view is `@PageTitle("Home")`. A view that simply does `add(new BreadcrumbTrail())` shows "Home › Customers › Acme Corp › Orders" — one item per matched route, each labeled with that route's view title.*
+
+---
+
+## 14. Flow: Opting out of automatic trail population
+
+The Flow wrapper lets the application disable automatic population so the breadcrumb shows only the items the application provides explicitly. Opting out is a per-instance choice and does not affect other breadcrumbs in the application.
+
+*Example: A product catalog view builds its trail from category data rather than the URL structure. It opts the breadcrumb out of automatic population and supplies the items itself, so router-derived ancestors are not mixed in.*
+
+---
+
+## 15. Flow: Sitemap parent annotation overrides URL-based parent lookup
+
+A Flow `@Route` class can carry an annotation that declares its sitemap parent. When the annotation is present, the automatic trail uses the declared parent for that view instead of inferring one from the URL hierarchy. Walking continues from the declared parent using the same rules.
+
+*Example: A route registered at `/orders/edit/123` declares its sitemap parent as the orders list view. The breadcrumb shows "Home › Orders › Edit Order" instead of the URL-derived "Home › Orders › Edit › Edit Order".*
+
+---
+
+## 16. Flow: Routes can dynamically supply their breadcrumb contribution
+
+A Flow `@Route` class can implement an interface that lets it dynamically provide what should appear in the breadcrumb for that view. The contribution is evaluated at navigation time, so it can depend on the data the view is currently showing, and it can replace the view's default item, add additional ancestors, or both.
+
+*Example: A `CustomerView` showing customer "Acme Corp" implements the interface and returns "Acme Corp" as its own label plus an extra ancestor "Enterprise" (the customer's segment). The breadcrumb shows "Home › Customers › Enterprise › Acme Corp" instead of a generic "Home › Customers › Customer".*
+
+---
+
+## Discussion
+
+Questions posed while producing this document, with the user's answers.
+
+**Q: How should the user navigate the expanded list of collapsed items with the keyboard?**
+
+Both menu-style arrow keys and linear Tab. The visual reads as a menu, so users coming from menu-bar / context-menu expect Up/Down to step through entries. At the same time, the entries are plain anchors and a screen-reader user (or anyone navigating the page entirely with Tab) expects to traverse them the same way they traverse any other link. Supporting both — Tab as the primary document-level mechanism, arrows as a menu-style convenience — covers both audiences without forcing one to adopt the other's interaction model. Escape closes the list regardless of how it was opened.
+
+**Q: When the breadcrumb trail is too long to fit the available width, how should the component handle overflow?**
+
+Collapse intermediate items progressively, starting from the item closest to the root, so the current item's immediate ancestors are preserved the longest. The root collapses only as a last resort; the current item never collapses. The rationale is that the root and the current item's nearby ancestors are the ones the user most likely wants to see or jump to.
+
+**Q: Should breadcrumb items support displaying icons alongside their text label?**
+
+Yes, items can optionally display an icon before their text. Useful for home icons, folder icons, etc.
+
+**Q: On small viewports (mobile), should the breadcrumb simplify its display?**
+
+No special mobile behavior — use the same overflow/collapse mechanism as on desktop.
+
+**Q: Which variants are in scope for this component?**
+
+Both web component and Flow (Java) wrapper — the standard for new Vaadin components.
+
+**Q: Should long item labels be truncated with an ellipsis?**
+
+No. Truncation of individual labels is not a component-level requirement — removed from scope.
+
+**Q: Should the navigation landmark have a default label (e.g., "Breadcrumb")?**
+
+No. The component identifies itself as a navigation landmark but does not provide a component-specific default label.
+
+**Q: Why does the Flow wrapper auto-populate the trail from the router by default?**
+
+A Flow application already declares its sitemap as `@Route` classes, so requiring every view to manually build a breadcrumb duplicates information the framework already has. Defaulting to router-derived items (req 13) lets the trivial case work with zero configuration. Apps that need full control can opt out per instance (req 14).
+
+**Q: What text does the auto-populated trail show for each item?**
+
+Each item is labeled with the matched route's view title — i.e., whatever Flow already uses as the page title for that route (the `@PageTitle` value, or a dynamically supplied title). Reusing the existing title means a route's breadcrumb label and browser tab title stay in sync without the developer having to declare them twice.
+
+**Q: Why support both a parent annotation and a runtime interface for influencing the trail?**
+
+URL hierarchy alone cannot express two common cases: (a) a route whose conceptual parent differs from its URL parent — e.g., an edit view whose parent is the list view, not the URL segment "edit" (req 15) — and (b) a trail that depends on the data the view is showing, such as inserting a customer's segment as an ancestor (req 16). A static annotation handles the first cleanly without runtime cost; a runtime interface handles the second. Together they cover the cases the URL-walking default cannot.
diff --git a/packages/breadcrumb-trail/spec/web-component-api.md b/packages/breadcrumb-trail/spec/web-component-api.md
new file mode 100644
index 00000000000..3f2106589e5
--- /dev/null
+++ b/packages/breadcrumb-trail/spec/web-component-api.md
@@ -0,0 +1,198 @@
+# BreadcrumbTrail Developer API
+
+## 1. Displaying the ancestor trail as links
+
+Covers requirement(s): 1, 2
+
+```html
+<vaadin-breadcrumb-trail>
+  <vaadin-breadcrumb-item path="/">Home</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs">Developer Guide</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs/api">API Reference</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs/api/auth">Authentication</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item>OAuth2</vaadin-breadcrumb-item>
+</vaadin-breadcrumb-trail>
+```
+
+**Why this shape:** Items with a `path` attribute render as links; the last item without `path` is the current page — visually distinct and not interactive. This follows the Side Nav convention (`path` attribute, child elements as items) and needs no extra boolean to mark the current item. The convention is simple: if it has a `path`, it's a link; if it doesn't, it's the current location.
+
+---
+
+## 2. Optionally omitting the current page
+
+Covers requirement(s): 3
+
+```html
+<!-- Current page omitted — all items have a path -->
+<vaadin-breadcrumb-trail>
+  <vaadin-breadcrumb-item path="/">Home</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs">Developer Guide</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs/api">API Reference</vaadin-breadcrumb-item>
+</vaadin-breadcrumb-trail>
+```
+
+**Why this shape:** No extra API needed. When every item has a `path`, every item is a link and no current-page indicator appears. The application simply decides what to include in the trail.
+
+---
+
+## 3. Customizable separator
+
+Covers requirement(s): 4, 5, 12
+
+```html
+<!-- Default: theme renders a chevron separator between items -->
+<vaadin-breadcrumb-trail>
+  <vaadin-breadcrumb-item path="/">Home</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/products">Products</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item>Laptops</vaadin-breadcrumb-item>
+</vaadin-breadcrumb-trail>
+```
+
+```css
+/* Override the separator icon via the CSS custom property */
+vaadin-breadcrumb-trail {
+  --vaadin-breadcrumb-trail-separator: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="7" y1="4" x2="17" y2="20"/></svg>');
+}
+```
+
+**Why this shape:** The separator is rendered as a `::after` pseudo-element on each item using `mask-image`, matching the pattern used across Vaadin components (select's toggle button, combo-box's dropdown arrow, clear buttons). The pseudo-element has `background: currentColor` shaped by `mask-image: var(--vaadin-breadcrumb-trail-separator)`. Applications override the separator by setting the CSS custom property on the item. The theme handles flipping the separator direction in RTL contexts. This keeps the HTML clean — separators are purely visual, styled through CSS, not DOM content.
+
+---
+
+## 4. Overflow collapse and expansion
+
+Covers requirement(s): 6, 7
+
+```html
+<!-- Overflow is automatic — no developer action needed -->
+<!-- The component progressively collapses items closest to the root first -->
+<vaadin-breadcrumb-trail>
+  <vaadin-breadcrumb-item path="/">Home</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs">Documents</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs/projects">Projects</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs/projects/2026">2026</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs/projects/2026/q1">Q1</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs/projects/2026/q1/reports">Reports</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item>Summary</vaadin-breadcrumb-item>
+</vaadin-breadcrumb-trail>
+```
+
+```js
+// The overflow button's accessible label is customizable via i18n
+const breadcrumb = document.querySelector('vaadin-breadcrumb-trail');
+breadcrumb.i18n = {
+  moreItems: 'Show hidden items'
+};
+```
+
+**Why this shape:** Overflow is an automatic responsive behavior — the component collapses items when they don't fit, starting from the item closest to the root. No developer configuration is needed for the collapse itself. The overflow indicator opens a menu showing the hidden items. The `i18n` pattern follows Menu Bar's convention for localizing internal button labels.
+
+---
+
+## 5. Icons alongside item text
+
+Covers requirement(s): 8
+
+```html
+<vaadin-breadcrumb-trail>
+  <vaadin-breadcrumb-item path="/">
+    <vaadin-icon icon="vaadin:home" slot="prefix"></vaadin-icon>
+    Home
+  </vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs">
+    <vaadin-icon icon="vaadin:folder" slot="prefix"></vaadin-icon>
+    Documents
+  </vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item>Report.pdf</vaadin-breadcrumb-item>
+</vaadin-breadcrumb-trail>
+```
+
+**Why this shape:** The `prefix` slot follows Side Nav's convention for placing icons before item text. Icons are optional — items without a prefix slot are plain text. This uses Vaadin's existing `<vaadin-icon>` component rather than introducing a new icon mechanism.
+
+---
+
+## 6. Dynamic trail updates
+
+Covers requirement(s): 9
+
+```js
+const breadcrumb = document.querySelector('vaadin-breadcrumb-trail');
+
+// Replace the trail by mutating the light-DOM children directly
+breadcrumb.replaceChildren(
+    Object.assign(document.createElement('vaadin-breadcrumb-item'),
+                  { textContent: 'Home', path: '/' }),
+    Object.assign(document.createElement('vaadin-breadcrumb-item'),
+                  { textContent: 'Electronics', path: '/electronics' }),
+    Object.assign(document.createElement('vaadin-breadcrumb-item'),
+                  { textContent: 'Laptops', path: '/electronics/laptops' }),
+    Object.assign(document.createElement('vaadin-breadcrumb-item'),
+                  { textContent: 'Gaming' }));
+```
+
+**Why this shape:** The component reflects whatever `<vaadin-breadcrumb-item>` children sit in its light DOM — applications drive dynamic updates with the standard DOM APIs (`appendChild`, `replaceChildren`, framework-level rendering, etc.). No parallel `items` data-array property is exposed: the declarative form already covers every dynamic case, and a second API would need its own parser, item-construction logic, and rules for how the two forms interact (see Discussion: "Why is there no programmatic `items` property?").
+
+---
+
+## 7. Navigation landmark
+
+Covers requirement(s): 10
+
+```html
+<!-- The component renders a <nav> element automatically -->
+<!-- The application provides an accessible label -->
+<vaadin-breadcrumb-trail aria-label="Product navigation">
+  <vaadin-breadcrumb-item path="/">Home</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/products">Products</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item>Laptops</vaadin-breadcrumb-item>
+</vaadin-breadcrumb-trail>
+```
+
+**Why this shape:** The component renders as a `<nav>` landmark automatically. The application provides the `aria-label` when it wants to distinguish this breadcrumb from other landmarks on the page — following the universal rule that accessible names are customizable. No component-specific API is needed beyond standard ARIA attributes.
+
+---
+
+## 8. Current page announced as current
+
+Covers requirement(s): 11
+
+```html
+<!-- No developer action needed -->
+<!-- The component automatically adds aria-current="page" to the last item
+     when it has no path (i.e., it represents the current page) -->
+<vaadin-breadcrumb-trail>
+  <vaadin-breadcrumb-item path="/">Home</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item path="/docs">Docs</vaadin-breadcrumb-item>
+  <vaadin-breadcrumb-item>OAuth2</vaadin-breadcrumb-item>  <!-- aria-current="page" applied automatically -->
+</vaadin-breadcrumb-trail>
+```
+
+**Why this shape:** The ARIA Authoring Practices Guide specifies `aria-current="page"` for the current breadcrumb item. Since the component already knows which item is current (the last item, if it has no `path`), it applies this automatically — no developer action required.
+
+---
+
+## Discussion
+
+**Q: Should the breadcrumb item's link destination attribute be named `href` or `path`?**
+
+`path` — consistent with Vaadin Side Nav and the DESIGN_GUIDELINES breadcrumb example. Although `href` is the standard HTML attribute, `path` keeps Vaadin navigation components consistent.
+
+**Q: How should the separator be customizable?**
+
+CSS `mask-image` pattern — matching how the select toggle button, combo-box dropdown arrow, and clear buttons render their icons. The separator is a `::after` pseudo-element on each item with `background: currentColor` shaped by `mask-image`. Applications override via the `--vaadin-breadcrumb-trail-separator` CSS custom property on `vaadin-breadcrumb-trail`, which cascades to all items. No slot needed; separators are a theme/visual concern, not structural content.
+
+**Q: Should breadcrumb items support a `suffix` slot?**
+
+No. We considered it but decided not to add it before we have a real use case for it. The `prefix` slot covers the known use case (icons). A `suffix` slot can be added later if a concrete need arises.
+
+**Q: Where should the separator CSS custom property override be applied?**
+
+On `vaadin-breadcrumb-trail` (the parent), not on individual items. The property cascades down to all items, keeping the override in one place.
+
+**Q: Should the separator `mask-image` reference the SVG directly or via a CSS custom property?**
+
+Via a CSS custom property (`--vaadin-breadcrumb-trail-separator`). The base styles set `mask-image: var(--vaadin-breadcrumb-trail-separator)` on the `::after` pseudo-element, and applications override the custom property to change the icon. This matches how other Vaadin components handle icon customization.
+
+**Q: Why is there no programmatic `items` property?**
+
+An earlier revision exposed a parallel `items` array on `<vaadin-breadcrumb-trail>` — `{ text, path }[]` mirroring the declarative form — on the assumption that "both should coexist". That assumption was reconsidered: across the Vaadin component set only `<vaadin-select>` exposes both, and only because of overlay-teleportation limits, not as a general rule. Unlike `<vaadin-menu-bar>` (where nested sub-menus make a declarative API impractical, see [#925](https://github.com/vaadin/web-components/issues/925)), the breadcrumb trail's flat structure expresses cleanly through `<vaadin-breadcrumb-item>` light-DOM children — and standard DOM APIs (`appendChild`, `replaceChildren`, framework rendering) already cover every dynamic case. A parallel `items` array would need its own parser, item construction, and merge rules with the declarative form for no concrete benefit; adding it later if a real need emerges is strictly additive.
diff --git a/packages/breadcrumb-trail/spec/web-component-spec.md b/packages/breadcrumb-trail/spec/web-component-spec.md
new file mode 100644
index 00000000000..a0a0c17e08a
--- /dev/null
+++ b/packages/breadcrumb-trail/spec/web-component-spec.md
@@ -0,0 +1,280 @@
+# BreadcrumbTrail Web Component Specification
+
+> This component is experimental. Enable the feature flag before importing:
+> `window.Vaadin.featureFlags.breadcrumbTrailComponent = true`
+
+## Key Design Decisions
+
+1. **Two custom elements: `<vaadin-breadcrumb-trail>` and `<vaadin-breadcrumb-item>`** — Follows the same container-plus-items shape as `<vaadin-side-nav>` / `<vaadin-side-nav-item>`. Items are light DOM children of the container, observed via a `SlotController`. Enables the declarative HTML API required by DESIGN_GUIDELINES.md.
+
+2. **`path` attribute on items renders an `<a>` element in shadow DOM** — Matches `<vaadin-side-nav-item>`'s pattern: `path` maps to the `href` attribute of an internal `<a>`. When `path` is absent, the item renders a `<span>` instead. The rendered `<a>` is a plain link — router-agnostic per DESIGN_GUIDELINES.md. (See web-component-api.md §1.)
+
+3. **Current page is the last item without `path`** — No explicit `current` boolean property. The container detects that the last slotted item has no `path` and applies `aria-current="page"` and the `current` state attribute to it. This differs from `<vaadin-side-nav-item>`, which has a `current` property driven by URL matching — breadcrumbs don't do path matching. (See web-component-api.md §1, §8.)
+
+4. **Declarative items only — no programmatic `items` property.** Items are always `<vaadin-breadcrumb-item>` light-DOM children of the container. Unlike `<vaadin-menu-bar>` (where nested sub-menus make a declarative API impractical, see [#925](https://github.com/vaadin/web-components/issues/925)) the breadcrumb trail's flat structure is straightforward to express declaratively, so a parallel `items` array would be redundant.
+
+5. **Separator via `mask-image` CSS on an `::after` pseudo-element** — A separator pseudo-element is rendered on every element that sits in the list flow: on `<vaadin-breadcrumb-item>` via `:host::after` (in the item's base styles) and on `[part="overflow"]` via `::after` (in the container's base styles). Both use the same `mask-image` pattern from button-base-styles (background: currentColor, shaped by mask-image) and the same `--vaadin-breadcrumb-trail-separator` custom property, which defaults to `--_vaadin-icon-chevron-right`. In RTL, the icon is flipped via `transform: scaleX(-1)`. (See web-component-api.md §3.)
+
+6. **Progressive overflow collapse using `ResizeMixin`** — The container uses `ResizeMixin` to detect when items don't fit. Items collapse from closest-to-root first, replacing collapsed items with an overflow button (`…`). The overflow button opens a dedicated `<vaadin-breadcrumb-trail-overlay>` element (extending `OverlayMixin`) that lists the hidden items. Using the shared overlay infrastructure — rather than a hand-rolled `position: fixed` panel in shadow DOM — brings focus trapping, stacking-context handling, top-layer rendering via the popover API, and outside-click/Escape handling for free. The `i18n` property (via `I18nMixin`) allows localizing the overflow button's `aria-label`. (See web-component-api.md §4.)
+
+7. **Navigation landmark via `role="navigation"` on the host** — `<vaadin-breadcrumb-trail>` sets `role="navigation"` on itself rather than wrapping its shadow DOM around an inner `<nav>`. The application supplies the accessible name via `aria-label` directly on the host. No default label is provided. (See web-component-api.md §7.)
+
+8. **List item semantics via `role="listitem"` on the host** — `<vaadin-breadcrumb-item>` sets `role="listitem"` on itself rather than wrapping its shadow DOM around an inner `<li>`. This keeps both components free of redundant semantic wrappers, consistent with the design rule in DESIGN_GUIDELINES.md.
+
+9. **No `suffix` slot on items** — Only a `prefix` slot is provided, matching the known use case (icons). (See web-component-api.md Discussion.)
+
+---
+
+## Implementation
+
+### Elements
+
+**`<vaadin-breadcrumb-trail>`** — Container element
+
+The host carries `role="navigation"`. Items are distributed across two slots so the overflow element can sit in the DOM between the root item and the rest — ensuring DOM order matches the visual order `[root] [overflow] [rest…]` per DESIGN_GUIDELINES.
+
+Shadow DOM:
+```html
+<div role="list" part="list">
+  <slot name="root"></slot>
+  <div role="listitem" part="overflow" hidden>
+    <button part="overflow-button"
+            aria-label="…"
+            aria-haspopup="true"
+            aria-expanded="false">
+      <!-- ::before pseudo-element renders ellipsis icon via mask-image -->
+    </button>
+  </div>
+  <slot></slot>
+</div>
+<vaadin-breadcrumb-trail-overlay
+  .owner="${this}"
+  .opened="${this._overlayOpened}"
+  .renderer="${this._overlayRenderer}"
+  .positionTarget="${this._overflowButton}"
+  exportparts="overlay, content: overlay-content"
+>
+  <slot name="overlay"></slot>
+</vaadin-breadcrumb-trail-overlay>
+```
+
+The `<div role="list">` is used instead of `<ol>` because (a) `<ol>` accepts only `<li>` children per HTML spec, and the slotted elements are `<vaadin-breadcrumb-item>`, and (b) `<ol>`/`<ul>` with `list-style: none` has its list role stripped by Safari/VoiceOver, which would suppress "list with N items" announcements. An explicit `role="list"` is immune to both issues.
+
+`<vaadin-breadcrumb-trail-overlay>` is rendered directly in the breadcrumb's shadow DOM, matching the convention of `<vaadin-combo-box>`, `<vaadin-avatar-group>`, `<vaadin-menu-bar-submenu>`, and other Vaadin overlay-hosting components. The breadcrumb's renderer writes hidden-item links into the **light DOM** projected through `<slot name="overlay">` (not into the overlay's `[part="content"]` shadow tree) so global CSS can style them. To make this work, the overlay sets `_rendererRoot` to the host of the slotted light-DOM container, mirroring the pattern in `SelectOverlayMixin`.
+
+| Property | Type | Default | Reflected | Description |
+|---|---|---|---|---|
+| `i18n` | `{ moreItems?: string }` | `{ moreItems: '' }` | No | Internationalization object. `moreItems` sets the `aria-label` of the overflow button. |
+
+| Slot | Description |
+|---|---|
+| `root` | The first `<vaadin-breadcrumb-item>` in the trail. The container assigns `slot="root"` to the first item automatically — the application does not set it. |
+| (default) | All remaining `<vaadin-breadcrumb-item>` elements in the trail. |
+
+| Part | Description |
+|---|---|
+| `list` | The element with `role="list"` wrapping all items. |
+| `overflow` | The listitem element containing the overflow button. |
+| `overflow-button` | The button that reveals collapsed items. |
+
+The overflow overlay's outer panel and its inner wrapper live on `<vaadin-breadcrumb-trail-overlay>` and are re-exported on the breadcrumb host through `exportparts="overlay, content: overlay-content"` — the overlay's `content` part is renamed to `overlay-content` on export so it does not collide with anything else themes might expect on the breadcrumb. Themes target them as `vaadin-breadcrumb-trail::part(overlay)` and `vaadin-breadcrumb-trail::part(overlay-content)`. The `<vaadin-breadcrumb-trail-overlay>` element itself is an internal implementation detail and is not part of the theming contract.
+
+| State attribute | Description |
+|---|---|
+| `has-overflow` | Set when one or more items are collapsed into the overflow overlay. |
+
+| CSS Custom Property | Default | Description |
+|---|---|---|
+| `--vaadin-breadcrumb-trail-separator` | `var(--_vaadin-icon-chevron-right)` | The mask-image icon used as the separator between items. Set on `<vaadin-breadcrumb-trail>` to change the separator for all items. |
+
+Internal behavior:
+
+- **Slot observation and root assignment.** The breadcrumb subclasses `SlotController` and overrides `initNode`/`initCustomNode` to watch the children. When children change, the controller sets `slot="root"` on the first `<vaadin-breadcrumb-item>` child and removes `slot` from any previous holder. This routes the first item into the named `root` slot in shadow DOM, so the overflow element sits in the DOM between the root and the rest — matching visual order. The same controller pass also re-evaluates overflow detection and `current` state on the last item.
+- **Overflow detection.** On resize (via `ResizeMixin`) and on slot changes, the component measures whether all items fit within the container width. If not, it progressively hides items starting from the one closest to the root (the first default-slot item), setting a `data-overflow-hidden` attribute on each hidden item. If further space is needed, the root item collapses too. The last item (current page) never collapses. Hidden items are listed in the overflow overlay.
+- **Overlay management.** The breadcrumb renders `<vaadin-breadcrumb-trail-overlay>` directly in its shadow DOM, with `.owner` bound to the host, `.opened` bound to an internal reactive state, `.positionTarget` bound to the overflow button, and `.renderer` bound to a callback that populates the overlay's content with links for the currently hidden items. Clicking the overflow button toggles `_overlayOpened`; `OverlayMixin` handles outside-click, Escape, focus handling, top-layer rendering via the popover API, and stacking. The breadcrumb does not touch positioning or event wiring beyond that.
+- **Overflow separator.** The overflow element sits in the list flow between the root and the rest, so it needs a separator after it when visible. The container's base styles render a `[part="overflow"]::after` pseudo-element using the same `mask-image` + `currentColor` pattern as `<vaadin-breadcrumb-item>`, reading the same `--vaadin-breadcrumb-trail-separator` custom property, and applying the same RTL flip (`transform: scaleX(-1)`). When `has-overflow` is not set, the overflow element is hidden, so the separator is not visible either.
+
+---
+
+**`<vaadin-breadcrumb-item>`** — Individual breadcrumb item
+
+The host carries `role="listitem"`. A separator pseudo-element is attached directly to the host via `:host::after`.
+
+Shadow DOM:
+```html
+<a href="..." part="link">
+  <slot name="prefix"></slot>
+  <span part="label">
+    <slot></slot>
+  </span>
+</a>
+<!-- :host::after renders the separator via mask-image -->
+```
+
+When `path` is not set (current page):
+```html
+<span part="nolink">
+  <slot name="prefix"></slot>
+  <span part="label">
+    <slot></slot>
+  </span>
+</span>
+```
+
+The outer wrapper carries `part="link"` when the item is interactive and `part="nolink"` whenever it is rendered as plain text instead of a link — most commonly the current page, but also any item the application chooses to display non-interactively (for example an ancestor the user has no permission to navigate to). Distinct part names let themes target the two cases without `:not([path])` selectors and without overloading any single state attribute.
+
+| Property | Type | Default | Reflected | Description |
+|---|---|---|---|---|
+| `path` | `string \| null \| undefined` | `undefined` | No | The URL to navigate to. When set, the item renders as an `<a>` link. When absent, the item renders as a non-interactive `<span>`. |
+
+| Slot | Description |
+|---|---|
+| (default) | Text label of the breadcrumb item. |
+| `prefix` | Content before the label (typically a `<vaadin-icon>`). |
+
+| Part | Description |
+|---|---|
+| `link` | The `<a>` element containing the label, when the item is interactive (`path` is set). |
+| `nolink` | The `<span>` element containing the label, when the item is rendered as plain text rather than as a link (the current page, or any item where `path` is not set). Mutually exclusive with `link`. |
+| `label` | The `<span>` wrapping the default slot text. Present in both cases. |
+
+| State attribute | Description |
+|---|---|
+| `current` | Set by the parent `<vaadin-breadcrumb-trail>` on the last item when it has no `path`. |
+| `has-prefix` | Set when the `prefix` slot has content. |
+
+Internal behavior:
+
+- **Link rendering.** When `path` is set, renders `<a href="${path}" part="link">`, matching the approach in `<vaadin-side-nav-item>`. When `path` is not set, renders `<span part="nolink">`. The `<a>` is a plain HTML link — no router integration, no click interception. SPA routers intercept link clicks at the document level.
+- **Separator rendering.** A `:host::after` pseudo-element renders the separator. It uses `background: currentColor` with `mask-image: var(--vaadin-breadcrumb-trail-separator)`, following the button-base-styles pattern. The last item's separator is hidden via `:host(:last-of-type)::after { display: none }`. Items with the `current` attribute also hide the separator. The same separator styling is duplicated on the container's `[part="overflow"]::after` (see the container's Overflow separator behavior) so the overflow element visually matches peer items in the list flow.
+- **RTL separator flip.** In RTL contexts, `:host::after` gets `transform: scaleX(-1)`.
+- **`aria-current="page"`.** When the parent sets the `current` state attribute on the host, the inner `<span part="nolink">` element gets `aria-current="page"`.
+- **Prefix slot.** A `SlotController` observes the `prefix` slot and toggles `has-prefix` on the host for styling.
+
+---
+
+**`<vaadin-breadcrumb-trail-overlay>`** — Overflow overlay
+
+Internal element used only by `<vaadin-breadcrumb-trail>`. Not intended for application use. Built on `OverlayMixin` plus `PositionMixin` (both from `packages/overlay`) and a new `BreadcrumbTrailOverlayMixin`, matching the pattern used by other Vaadin overlays: `<vaadin-combo-box-overlay>` pairs these with `ComboBoxOverlayMixin`, `<vaadin-menu-bar-overlay>` with `MenuOverlayMixin`, and so on. The component-specific mixin carries any overlay behavior specific to the host component (theme-attribute propagation, position adjustments, close-behavior tweaks). `PositionMixin` is what provides the `positionTarget` property used by the breadcrumb to anchor the overlay to the overflow button.
+
+Shadow DOM:
+```html
+<div part="overlay">
+  <div part="content" role="list">
+    <slot></slot>
+  </div>
+</div>
+```
+
+The element exposes no public properties or slots of its own — it inherits everything it needs from `OverlayMixin` and `PositionMixin`. The breadcrumb binds the inherited `opened`, `owner`, `renderer`, and `positionTarget` properties internally; applications do not set them.
+
+| Part | Description |
+|---|---|
+| `overlay` | The outer panel. Inherited `OverlayMixin` part naming. Re-exported on the breadcrumb host as `overlay` via `exportparts`. |
+| `content` | The inner wrapper holding the overlay content. Carries `role="list"` so the slotted `<vaadin-breadcrumb-item>` elements (each `role="listitem"`) form a valid ARIA list. Inherited `OverlayMixin` part naming. Re-exported on the breadcrumb host as **`overlay-content`** via `exportparts="content: overlay-content"`, so theme authors targeting the breadcrumb's host write `vaadin-breadcrumb-trail::part(overlay-content)` and there is no ambiguity with the breadcrumb's own parts. |
+
+Internal behavior:
+
+- **Light-DOM rendering via `_rendererRoot`.** The overlay sets `_rendererRoot` to a host that lives in the breadcrumb's light DOM (slotted through `<slot name="overlay">` from the breadcrumb host into the overlay's default slot). The breadcrumb's `renderer` writes the hidden-item `<vaadin-breadcrumb-item>` elements into that light-DOM root rather than into the overlay's shadow `[part="content"]`, so global page CSS reaches them. This mirrors the pattern in `SelectOverlayMixin`.
+- **Top-layer rendering.** `OverlayMixin` sets `popover="manual"` on the host in `firstUpdated()`, promoting the overlay to the browser's top layer when opened. The overlay renders above sibling and ancestor content, immune to `overflow: hidden` clipping and z-index stacking issues, even though the element itself sits in the breadcrumb's shadow DOM.
+- **Close on outside click and Escape.** Provided by `OverlayMixin`. The breadcrumb does not re-implement either.
+- **Positioning relative to the overflow button.** Driven by the `positionTarget` property from `PositionMixin`, matching the convention used by `<vaadin-combo-box-overlay>` and `<vaadin-avatar-group-overlay>`.
+- **Keyboard interaction within the open overlay.** Items are reachable via two parallel mechanisms:
+  - **Tab order** — links are part of the document tab cycle, so users navigating the page with Tab traverse them in DOM order. This matches every other anchor on the page and is the path screen-reader users naturally take.
+  - **Arrow keys** — Up/Down arrows move focus between adjacent links inside the open overlay (Home/End jump to first/last). The overlay reads as a menu visually, so menu-style keyboard navigation is supported alongside tabbing. Pressing `Tab` while an item is focused continues the document tab cycle (does not trap focus inside the overlay); `Escape` closes the overlay and returns focus to the overflow button.
+
+---
+
+## Reuse and Proposed Adjustments to Existing Modules
+
+### `packages/component-base/src/styles/style-props.js` — Modification needed
+
+Add a `--_vaadin-icon-chevron-right` icon definition alongside the existing `--_vaadin-icon-chevron-down`:
+
+```css
+--_vaadin-icon-chevron-right: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>');
+```
+
+The breadcrumb separator defaults to a right-pointing chevron. This icon does not exist in the shared icon set.
+
+### `packages/component-base/src/i18n-mixin.js` — Used as-is
+
+Provides the `i18n` property with a `moreItems` key for localizing the overflow button's `aria-label`.
+
+### `packages/component-base/src/resize-mixin.js` — Used as-is
+
+Provides `_onResize()` callbacks when the host element's size changes. The breadcrumb container overrides this to trigger overflow detection.
+
+### `packages/component-base/src/slot-controller.js` — Used as-is (extended)
+
+The breadcrumb container subclasses `SlotController` and overrides `initNode`/`initCustomNode` to react when `<vaadin-breadcrumb-item>` children are added or removed.
+
+### `packages/overlay/src/vaadin-overlay-mixin.js` — Used as-is
+
+`<vaadin-breadcrumb-trail-overlay>` extends `OverlayMixin` for the overflow overlay. Provides `opened` / `owner` / `renderer`, top-layer rendering via the popover API, outside-click / Escape closing, focus trapping, and stacking via `OverlayStackMixin`. No modification needed — the overlay is structurally identical to `<vaadin-menu-bar-overlay>`.
+
+### `packages/overlay/src/vaadin-overlay-position-mixin.js` (`PositionMixin`) — Used as-is
+
+`<vaadin-breadcrumb-trail-overlay>` extends `PositionMixin` for the `positionTarget` property used to anchor the overlay to the overflow button. Same usage pattern as `<vaadin-combo-box-overlay>` and `<vaadin-avatar-group-overlay>`. No modification needed.
+
+### `packages/select/src/vaadin-select-overlay-mixin.js` — Reference for `_rendererRoot`
+
+`<vaadin-breadcrumb-trail-overlay>` follows the `_rendererRoot` pattern from `SelectOverlayMixin` so the renderer writes into a light-DOM root projected through `<slot name="overlay">` rather than into the overlay's shadow `[part="content"]`. This lets global page CSS style the rendered hidden-item links. No code is reused directly; `SelectOverlayMixin` is named here as the implementation reference.
+
+---
+
+## Discussion
+
+Decisions made during specification review, with their reasoning.
+
+**Q: Why is there no programmatic `items` property?**
+
+An earlier revision exposed an `items` data array (`{ text, path }[]`) on `<vaadin-breadcrumb-trail>` mirroring the declarative API, on the principle that "both should coexist". In review, that principle was reconsidered — across the Vaadin component set only `<vaadin-select>` exposes both, and that was justified by overlay-teleportation limits, not by a general rule. Unlike `<vaadin-menu-bar>` (where nested sub-menus make a declarative API impractical, see [#925](https://github.com/vaadin/web-components/issues/925)), the breadcrumb trail's flat structure is straightforward to express declaratively. Dropping the parallel API removes a non-trivial chunk of implementation (an `items`-driven Lit `render()` pass plus the `BreadcrumbItemData` type) and still covers every documented use case via slotted `<vaadin-breadcrumb-item>` children. If a real need for the data-array form emerges later it can be added; until then it is intentionally absent.
+
+**Q: Why does the overlay's renderer write into light DOM via a slot rather than directly into `[part="content"]`?**
+
+So global page CSS can style the rendered hidden-item links. Anything written into the overlay's shadow `[part="content"]` is unreachable from page-level stylesheets, which would force users into `::part` workarounds and break the styling contract that other overlay-hosting components (notably `<vaadin-select>`) already establish. The overlay sets `_rendererRoot` to a light-DOM host slotted through `<slot name="overlay">` — the same mechanism `SelectOverlayMixin` uses — and the breadcrumb's renderer writes there.
+
+**Q: Why expose the `overlay` and `content` parts on the breadcrumb host rather than on `<vaadin-breadcrumb-trail-overlay>`?**
+
+`<vaadin-breadcrumb-trail-overlay>` is an internal element — applications and theme authors should not need to know it exists. Re-exporting its parts via `exportparts="overlay, content"` lets themes target `vaadin-breadcrumb-trail::part(overlay)` directly, which keeps the theming surface inside the public element name and avoids leaking the overlay's identity into stylesheet selectors.
+
+**Q: Why is the overlay's `content` part re-exported as `overlay-content` on the breadcrumb host?**
+
+`OverlayMixin` names the outer panel `overlay` and the inner wrapper `content`. Re-exporting both names verbatim onto `<vaadin-breadcrumb-trail>` would expose `vaadin-breadcrumb-trail::part(content)` to theme authors — and "content" reads as if it should refer to the visible trail of items, not to the inner wrapper of the overflow popup that only appears when items collapse. To avoid that misreading, the overlay element re-exports `content` as `overlay-content` on the breadcrumb host (`exportparts="overlay, content: overlay-content"`). The overlay's `overlay` part keeps its name on the host because there is no comparable ambiguity. Inside `<vaadin-breadcrumb-trail-overlay>` itself the part is still called `content`, matching every other Vaadin overlay; the rename is a host-side disambiguation only.
+
+**Q: Why does the non-link rendering carry `part="nolink"` rather than reusing `part="link"`?**
+
+Distinct part names match the two cases the item can be in (interactive anchor vs. non-interactive plain text). Reusing `part="link"` for both forces theme authors to write `vaadin-breadcrumb-item:not([path])::part(link)` to target non-link items and reads as if a non-link item were a link — which it explicitly is not. An earlier revision used `part="current"`, but that name described only one *reason* for the non-link rendering — the last item with no path. Items can also be rendered as plain text for other reasons (e.g. an ancestor the user has no permission to navigate to), and `[part="current"]` on a non-current item would be misleading. The neutral name `nolink` covers every reason an item might render without an anchor, without favouring one cause over another. The `current` state attribute on the host stays as a separate concept; themes that want to single out the current-page case combine the two: `vaadin-breadcrumb-item[current]::part(nolink)`.
+
+**Q: Why does the overflow overlay support both arrow keys and Tab?**
+
+The overlay reads visually as a menu, so users coming from menu-bar / context-menu expect Up/Down arrow keys to move between entries. At the same time, it is a list of plain anchors, and screen-reader users (plus power users navigating the page entirely with Tab) expect to traverse those anchors via the standard tab cycle. Supporting both — Tab as the primary, document-level focus mechanism, arrow keys as a menu-style convenience — covers both audiences without forcing one to adopt the other's interaction model. Escape closes the overlay regardless of how focus arrived.
+
+**Q: Should `<vaadin-breadcrumb-item>` expose a `target` property?**
+
+No. An earlier revision included `target` mirroring `<vaadin-side-nav-item>`'s support for `_blank`-style anchor targets. It was removed because a breadcrumb trail represents the user's position within a single application hierarchy, and opening an ancestor in a new tab is not a supported interaction — it would produce two tabs of the same application, neither reflecting the other's state. The rendered `<a>` still honours standard HTML link behaviour (middle-click, Ctrl/Cmd-click for user-driven new-tab/new-window opens) because the browser handles those on its own; only the programmatic `target` attribute is dropped. Reintroducing `target` is strictly additive if a concrete use case emerges.
+
+**Q: Should the overflow panel be called a "dropdown"?**
+
+No. Vaadin components generally avoid the term "dropdown" — menu-bar, select, combo-box, and AvatarGroup all expose `overlay` and `content` parts. The breadcrumb follows the AvatarGroup pairing: an `overlay` part for the outer panel and a `content` part for the inner wrapper holding the collapsed items.
+
+**Q: Should `SlotChildObserveController` be used to observe item children?**
+
+No. `SlotChildObserveController` bundles two concerns the breadcrumb does not need: observing `id`-attribute mutations for ARIA references (useful to field components) and firing a generic "content changed" event. For breadcrumb's needs — reacting when items are added or removed — subclassing `SlotController` and overriding `initNode`/`initCustomNode` is sufficient and keeps the dependency surface minimal.
+
+**Q: Should the shadow DOM wrap content in `<nav>` and each item in `<li>`?**
+
+No. Per the "Use `role` on the host instead of a semantic wrapper inside it" rule in DESIGN_GUIDELINES.md, `<vaadin-breadcrumb-trail>` carries `role="navigation"` on the host and `<vaadin-breadcrumb-item>` carries `role="listitem"` on the host. The inner list wrapper in the container is retained as a genuine exception — a single element cannot carry both the `navigation` and `list` roles, so the list semantics live on an inner element.
+
+**Q: Should the list wrapper be `<ol>` or a generic element with `role="list"`?**
+
+A generic element with explicit `role="list"`. Two reasons: (a) HTML `<ol>` accepts only `<li>` children, and the slotted items are `<vaadin-breadcrumb-item>` custom elements, so `<ol>` would be non-conforming; (b) Safari + VoiceOver strips the list role from `<ol>`/`<ul>` when `list-style: none` is applied (which a themed breadcrumb always applies), suppressing "list with N items" announcements. Explicit `role="list"` is immune to both issues.
+
+**Q: How is the overflow element positioned so it appears visually between the root and the rest of the items?**
+
+Two shadow slots with the overflow in shadow DOM between them: `<slot name="root"></slot>`, then `<div part="overflow">`, then `<slot></slot>`. The component's `SlotController` assigns `slot="root"` to the first `<vaadin-breadcrumb-item>` child automatically — the application doesn't set it. This keeps DOM order aligned with visual order `[root] [overflow] [rest…]`, satisfying the "focus order matches visual order" rule. The alternative considered — inserting the overflow as a light-DOM sibling between items — was rejected because it would add a component-authored element to the user's light DOM, changing `breadcrumb.children.length` and conflicting with the "light DOM is the application's territory" principle.
+
+**Q: Should the overflow panel use `OverlayMixin` or be a plain `<div>` positioned with `position: fixed`?**
+
+`OverlayMixin`, via a dedicated `<vaadin-breadcrumb-trail-overlay>` element. A hand-rolled fixed-positioned `<div>` in shadow DOM was considered but rejected — it would miss focus trapping, stacking-context handling, top-layer rendering via the popover API, and outside-click/Escape handling, all of which `OverlayMixin` provides for free and which other Vaadin overlays (menu-bar, combo-box, dialog, context-menu) already rely on. `<vaadin-breadcrumb-trail-overlay>` is rendered directly in the breadcrumb's shadow DOM with its properties (`owner`, `opened`, `renderer`, `positionTarget`, `exportparts`) bound to the breadcrumb's state — matching the pattern in `<vaadin-combo-box>`, `<vaadin-avatar-group>`, `<vaadin-menu-bar-submenu>`, and other overlay hosts.