recursica-skill-breadcrumb
Rules for the Recursica breadcrumb — when depth warrants a trail, what goes in the trail, the current page as plain text, and navigation-region accessibility. Use for breadcrumb trails and hierarchy paths. Not for the app shell — see recursica-skill-navigation; not for steps in a process — see recursica-skill-stepper.
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- recursica-skill-breadcrumb
- license
- MIT
- metadata
- { "author": "hi@borderux.com", "version": "0.2.0" }
- description
- Rules for the Recursica breadcrumb — when depth warrants a trail, what goes in the trail, the current page as plain text, and navigation-region accessibility. Use for breadcrumb trails and hierarchy paths. Not for the app shell — see recursica-skill-navigation; not for steps in a process — see recursica-skill-stepper.
03 SKILL.md 正文
Breadcrumb
A breadcrumb shows where the current page sits in the page hierarchy. A breadcrumb is a trail of items. An item names one page in the hierarchy. For example, the Order 1042 page sits inside the Orders section, so the trail ends with Orders, then Order 1042. Each item above the current page links back up to that item's page.
When to use a breadcrumb
- The application has a deep page hierarchy, more than one level below the home page.
recursica-skill-layouts-and-templatessets this rule. - The page must answer "Where am I?" by itself, without the navigation on screen. Headings and breadcrumbs answer the question.
- The persona moves through several levels or categories, such as Products, then Shoes, then Running shoes. The persona needs to keep track of the current page's place along that deep path.
When not to use a breadcrumb
| Situation | Use instead |
|---|---|
| The application only ever has one level below the home page | Headings. A clear heading hierarchy shows the persona's location. See recursica-skill-navigation. |
| The breadcrumb would be the only way back to the parent page | Real navigation: a sidebar or a top bar. A breadcrumb is an extra aid for finding the way, not the main way. |
| The heading and the navigation already make the location clear | No breadcrumb. A breadcrumb that repeats a location the persona can already see is clutter. |
| The persona moves through ordered steps in a process | A stepper. See recursica-skill-stepper. |
| The persona switches between parts of one whole on a page | Tabs. Each tab has a separate route. See recursica-skill-tabs. |
| The breadcrumb would record the pages the persona has visited | A trail built from the page hierarchy. A breadcrumb shows how the pages are structured, not a history of visits. |
A breadcrumb is never the primary navigation. If a persona cannot leave a section without the breadcrumb, the problem is in the navigation, not the breadcrumb. See recursica-skill-navigation.
Variants
Use only the breadcrumb variants and options that the knowledge MCP server lists for the theme (the design a designer sets in Theme Forge: the token values, the components, and each component's variants, states and sizes). A designer can add variants and options in Theme Forge, so each theme can differ. Get the list with the server's component_api tool, and use the names the code uses. Never invent a variant or an option.
Do not set a variant, state or content option that the knowledge MCP server does not list for the theme.
- The separator. A separator is the mark between two items, such as a slash, a chevron or a dot. If the theme has a separator, use the theme's separator. Do not invent a separator. Which separator to use is an open question.
- Long trails. A long trail never scrolls horizontally.
recursica-skill-navigationforbids horizontal scrolling outright. No rule says yet how a long trail collapses, is cut off or overflows. The answer to that open question can never be horizontal scrolling. - Item content and item styles. A content variant sets what each item shows, such as a label only or an icon with a label. If the theme has a content variant, use the theme's content variant. If the theme has separate styles for a clickable item and the read-only current page, use the theme's styles. The content variant is an open question.
Rules
Build the trail from the page hierarchy, not from the pages the persona has visited. Two personas who reach the same page by different paths see the same trail. For example, the Order 1042 page shows one trail, whether the persona came from the Orders list or a search. A breadcrumb shows how the application's pages are structured.
Show the current page as the last item in the trail, and do not make the current page a link. Mark the current page clearly. A link to the current page does nothing when clicked, and leaves the persona on the same page.
Make every item before the current page a real link with a real href, to a page that exists. See recursica-skill-link.
Label each item with the name of the destination page, with no verb. For example, write "Orders", not "Go to orders".
- The label should match the heading on the destination page.
- A label may differ slightly when several places lead to the same page under names that fit each context.
When the label matches the heading, the persona who arrives sees that the trail led to the right page.
Never make a breadcrumb the only sign of the persona's location. A breadcrumb is one of three location signs. recursica-skill-navigation requires more than the selected state: headings, breadcrumbs, or both. The three signs are:
- the selected item in the navigation, such as Orders highlighted in the sidebar
- a clear heading hierarchy
- breadcrumbs, where the page hierarchy is deep enough to need breadcrumbs
recursica-skill-navigation also states that the selected navigation item alone is not enough.
Include the current page and only the levels above the current page. Leave out each of the following:
- sibling pages, such as other orders next to Order 1042
- filters, search settings and sort settings
- any modal the persona has open
Never point a breadcrumb item at a modal or a panel. A modal or a panel opens from a control on the page. A modal or a panel is not a page the persona navigates to. Opening a modal or a panel adds no entry to the browser history. See recursica-skill-navigation.
Never build a breadcrumb item that is only an icon, even when the theme has an icon-only option. An icon alone cannot name the destination page. For example, a house icon alone does not say which page the icon opens. If the theme has an icon-with-label content option, use text or an icon with a label. Otherwise, use text.
Never put the trail in a scrolling strip, and never shrink the trail to make the trail fit. A trail too long for the space means the page hierarchy is too deep. Raise the depth of the page hierarchy as a problem, instead of hiding the depth with layout. See recursica-skill-design-system-conventions.
Accessibility
The rules below add to the accessibility baseline in recursica-skill-design-system-conventions, including the focus ring, which every Recursica component follows.
A breadcrumb is a short line of links. Assistive technology, such as a screen reader, recognizes a trail only when the markup marks the breadcrumb as a trail. Three mistakes cause nearly all breadcrumb problems:
- a navigation region with no name
- a separator read aloud between every item
- a current page that links to the current page
Screen readers
- Mark the breadcrumb as a navigation region named "Breadcrumb". A page with more than one navigation region must name each region. A persona using a screen reader finds the regions in the landmark list (the list of labeled page regions a screen reader can jump between). Without a name on each region, the persona cannot tell the regions apart.
- Mark up the trail as a semantic list, ordered or unordered. All navigation is marked up as a list. The list markup tells a persona using a screen reader how many levels the trail has. The list markup also tells the persona where the current page sits among the levels.
- The current page is the last item, and the current page must be marked as current in code. Styling the current page to look current is not enough.
- Separators are decorative and must be silent. A slash or a chevron announced between every item turns a four-level trail into eight announcements. If the separator is a text character, hide the separator from assistive technology. If the breadcrumb component supplies the separator, do not add a second separator.
- Name each link after the page the link goes to. The link name must make sense when read with no text around the link. For example, "Orders" makes sense alone, and "Back" does not. A persona using a screen reader can open a list of the page's links. The list of links shows no text around each link.
- Never rely on position alone to mark the current page. "Last in the list" is not a state a screen reader reports.
- Do not add a hidden copy of the trail or the page title for screen readers. The last breadcrumb item and the page's H1 are expected to name the same page. A hidden copy makes a screen reader read the page name a third time.
- An icon beside a label is decorative and silent. The label is the link name.
Keyboard and non-mouse navigation
- Every breadcrumb link is a tab stop (a place the Tab key lands), in visual order from left to right. Each breadcrumb link is a tab stop because the link has an
href. Do not add atabindexto force an order. - The current page cannot receive focus, because the current page is not a link.
- The whole trail must be reachable by keyboard, and the trail must not be the only way back. A persona who cannot reach or does not use the trail must still reach the parent page through the navigation.
- No part of the trail may appear only on hover. The rule covers each breadcrumb item and any collapsed part of the trail. A persona using a keyboard and a persona using touch cannot reach levels that appear only on hover.
- Enter follows a breadcrumb link, and Space does not. Browsers follow a link on Enter and not on Space. A breadcrumb item that responds to Space is a button, not a link.
- Do not intercept the modifier keys. Ctrl, Cmd, Shift and middle-click must reach the browser. The persona then chooses where the parent page opens, such as in a new tab.
Styling set by tokens
Never set or override the breadcrumb's styling. The theme sets every visual property of the breadcrumb, such as size, spacing, borders, colors and animation. Do not add extra containers or spacers to change the breadcrumb's look. If the design needs a look the theme does not give, raise the gap. See recursica-skill-design-router.
The breadcrumb's styling includes the separator's look, wherever the separator comes from, and the focus ring.
Related skills
recursica-skill-navigation— what counts as a location, routing and browser history, and list markup for navigation.recursica-skill-navigationalso covers showing location with the selected navigation item, headings and breadcrumbs, and the ban on horizontal scrolling.recursica-skill-buttons-links— link versus button, link label wording, and the tooltip an icon-only control needs.recursica-skill-design-system-conventions— never showing meaning in only one way, and fixing the structure instead of adding a workaround for a structure problem.
Only if used on the same screen
recursica-skill-link— realhrefvalues, labels that name the destination page, never disabling a link, and modifier-key behavior.recursica-skill-tabs— switching between parts of one whole on a single page, which is not a trail.
Open questions
- The separator. No one has decided which character the separator is, or whether the separator is an icon. If the theme has a separator, use the theme's separator. Otherwise, confirm with the user.
- Long trails. No one has decided whether a deep trail drops the middle levels, shortens the labels, or wraps. Horizontal scrolling is not an option.
- The content variant. Only the design-system website shows a content variant with Label only, Icon + Label, Icon only and Mixed options. Only the website shows separate styles for read-only items and clickable items. If the theme has the content variant or the item styles, use the theme's version. Otherwise, do not rely on either one without confirming with the user.
- The start of the trail. No rule says whether the trail starts at the application's home page or at the section's landing page.
- A level with no landing page. No rule says how the trail handles a level with no landing page. The level exists in the hierarchy above the current page, but has no route to link to. For example, a Settings group may hold pages but have no page of the group's own.
Pre-flight checklist
- [ ] The application's pages are nested, and the trail is not the only way back to the parent page.
- [ ] The selected navigation item and the page's heading hierarchy also show the location.
- [ ] The trail follows the page hierarchy, not the persona's click history.
- [ ] The trail holds the current page and only the levels above the current page.
- [ ] The last item is the current page. The current page is not a link, and is marked as current in code.
- [ ] Every item before the current page is a real link with a real
href, to a page that exists. - [ ] Each label names the destination page with no verb, and matches the heading on the destination page where possible.
- [ ] No breadcrumb item points to a modal or a panel.
- [ ] The trail is a named navigation region, and is marked up as a semantic list.
- [ ] Separators are hidden from assistive technology, and no separator is announced between items.
- [ ] No breadcrumb item is only an icon, and any decorative icon beside a label is silent.
- [ ] No hidden copy of the trail or the page title is added for screen readers.
- [ ] Every breadcrumb link is a tab stop, in visual order, and the current page cannot receive focus.
- [ ] No part of the trail depends on hover, and the modifier keys are not intercepted.
- [ ] The trail does not scroll horizontally, wrap into a strip, or shrink to fit.
- [ ] Every variant, state and content option is one the knowledge MCP server lists for the theme, under the code's name.
- [ ] No separator token is invented.
- [ ] No styling is set or overridden on the breadcrumb.
- [ ] No container or spacer is added to change the breadcrumb's look.
- [ ] Open questions were asked about, not decided: the separator, long trails, the content variant, the start of the trail, and a level with no landing page.
04 同仓库更多 Skills
recursica-skill-template
Replace with a description of the skill and its purpose.
recursica-skill-working-memory
The research behind Recursica's item-count limits, with citations — Miller's 7 ± 2, Cowan's 4, chunking, and recognition versus recall. Use when a decision turns on how many options, navigation items, or chips to show at once, or to justify or challenge a count. Not for choosing a control — see recursica-skill-selection-controls.
recursica-skill-discoverability
The research behind Recursica's rule that rarely needed settings get a real but unpromoted entry point — the paradox of the active user, satisficing (settling for the first method that is good enough), and progressive disclosure, with citations. Use when deciding whether to hide, promote, or build a configuration or customization feature, or to justify that choice. Not for item counts — see recursica-skill-working-memory.
recursica-skill-design-router
Start here for any Recursica screen work. The router says what to decide in what order, which skill owns each decision, which rule wins when two rules conflict, and when to confirm with the user instead of guessing. Load the router first to design, build, review, or refactor a screen, page, panel, or flow, or when rules seem to disagree or no rule applies. The router routes, and the owning skill holds the rules.
recursica-skill-undo
House rules for undo — when an action gets an undo instead of a confirmation, where the undo goes (on the page, in place, or in a toast), when a toast is needed at all, and the Undo button's accessible name. Use whenever an action can be reversed, or when choosing between an undo and a confirmation. Not for building the toast that holds an Undo button — see recursica-skill-toast. Not for the confirmation modal — see recursica-skill-buttons-links.
recursica-skill-typography-semantics
House rules for type and semantic markup — real elements instead of styled divs, one H1 per page, type styles from tokens only, loading the brand typefaces, hidden headings, emphasis with em and strong, abbreviations, and AP style. Use for headings, body copy, emphasis, and the markup under a visual hierarchy. Not for naming — see recursica-skill-names-and-terms.