[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7554EXR82TTQXDS9SW38CZ6":3,"skill-same:01M7554EXR82TTQXDS9SW38CZ6":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":30,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":33,"ownerDescription":6,"updatedAt":34,"install":35,"resources":48},"01M7554EXR82TTQXDS9SW38CZ6","recursica-skill-navigation",null,"House rules for navigation and tabs — top bar versus sidebar, item counts, sub-levels opening on click, active states, breadcrumbs, collapsible groups, overflow, permissions, routing and browser history, and correct use of tabs. Use for sidebars, top bars, menus, breadcrumbs, tab bars, and routes. Not for forms or steppers — see recursica-skill-forms.","borderux\u002Frecursica-knowledge","borderux","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F14911137?v=4","01M754SG94XX2Y7176KM2WGZG3","Border LLC","01M754SGA9E7YSNK6NWVMKMHYC",1,"MIT","https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge\u002Fblob\u002Fmain\u002Fskills\u002Fdesign-rules\u002Frecursica-skill-navigation\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: recursica-skill-navigation\ndescription: House rules for navigation and tabs — top bar versus sidebar, item counts, sub-levels opening on click, active states, breadcrumbs, collapsible groups, overflow, permissions, routing and browser history, and correct use of tabs. Use for sidebars, top bars, menus, breadcrumbs, tab bars, and routes. Not for forms or steppers — see recursica-skill-forms.\nlicense: MIT\nmetadata:\n  author: hi@borderux.com\n  version: 0.2.0\n---\n\n# Navigation and tabs\n\nThis skill holds the house rules for the navigation of an application. The rules cover:\n\n- primary and secondary navigation\n- showing the items under a navigation item\n- showing the persona where the persona is\n- overflow\n- routes and the browser history\n- tabs\n\nTreat each rule as a constraint. The rules are opinions, not neutral best practices.\n\nThe rules assume **complex enterprise web applications, designed for desktop first**, built on the Recursica design system. The design system decides how each component looks, including selected states, hover styling, spacing and color. This skill decides the structure, the interaction, and how routes behave.\n\n**Never build a control that moves the persona to a new place and does a second action in one click.** Each of the following is a separate outcome:\n\n- moving the persona to a new place\n- applying a filter\n- opening a region that holds content, such as a page, a panel or a modal\n- switching a tab\n\nWhen one click has two of the outcomes above, the control's label can honestly describe only one outcome.\n\n**If a destination must open already filtered, make the filtered view a separate destination with a separate route.** For example, a \"Late orders\" view gets a route separate from the Orders page. A \"Late orders\" link goes to that route, and the link itself applies no filter. See convention 6 in `recursica-skill-design-system-conventions`.\n\n**Make each navigation label name an object, not an action.** Write `Forms`, never `View forms`. `recursica-skill-names-and-terms` decides three questions about each navigation label:\n\n- what each item is called\n- whether a name is singular or plural\n- how much a term may be shortened\n\n## Governing principles\n\n1. **Make every location a route.** Give each place the persona navigates to a separate URL and an entry in the browser history. A modal or a panel that a trigger opens gets a URL whenever possible, but no history entry. The route rule is the most important rule in this skill, because designs break the route rule most often.\n2. **Fix the information architecture instead of working around the information architecture.** Information architecture is how the application's content is organized and labeled. `recursica-skill-information-architecture` sets the rules for information architecture. Each of the following is a symptom of a mistake in the information architecture:\n\n   - navigation that overflows, wraps or scrolls\n   - forms spread across tabs\n\n   Do not add a workaround to cope with the mistake.\n\n3. **The page itself must show where the persona is**, not only the navigation. Show the location with headings, breadcrumbs, or both. A selected state alone is not enough.\n\n## Routing and browser history\n\n**MUST give every view the persona can navigate to a separate route, reachable by the view's URL.** For example, the Orders page opens when the persona enters the Orders page's URL. Moving between views MUST add an entry to the browser history, so that the back and forward buttons work correctly. Designs break the route and history rule constantly. A missing route or history entry is a serious failure, not a finishing touch.\n\n**MUST NOT create history entries for modals or panels.** A trigger, such as a button, opens a modal or a panel. The persona does not navigate to a modal or a panel. The browser history should record the difference between a place in the application and a temporary state. A history entry for a modal or a panel erases that difference.\n\n**Give every panel, modal and tab an address whenever possible.** An address is a URL that opens the view with the panel, modal or tab already open. For example, a persona sends a coworker a link that opens the Orders page with one order's panel open. An address and a history entry are separate. Opening a panel or a modal changes the address, but adds no history entry.\n\n**A confirmation modal gets no address.** For example, \"Delete this invoice?\" has no URL. A link that opens a confirmation makes no sense. See `recursica-skill-panels-modals`.\n\nApply the routing and history rules equally to moving through primary navigation, secondary navigation and tabs.\n\n**Give each tab a separate route.** Give each tab a sub-path under the route of the view that holds the tabs. For example, an order page at `\u002Forders\u002F1042` puts the History tab at `\u002Forders\u002F1042\u002Fhistory`. A tab with a route can be linked to, restored, and reached with back and forward like any other location.\n\n**Restore a layout through routing, not through a remembered preference.** Do not build \"remember which tab was open\" as stored UI state. When each tab is a route, going back to a tab's URL restores the tab, and the back button works. Any approach beyond routing is a question of how the code is built, not a design decision.\n\n**Put the navigation on layer 0 beside the main content, unless the navigation or the main content needs containing.** A layer is a numbered background level, 0 to 3, that sets the colors of the components on that level. Layer 0 is the page itself.\n\n- Confirm with the user whether the navigation or the main content needs containing.\n- If containing is wanted, raise either the navigation or the main content to layer 1, not both.\n- Keep the same choice across the whole application.\n\n`recursica-skill-layers` sets the layer rules.\n\n## Horizontal top bar vs. vertical sidebar\n\n**Choose between a top bar and a sidebar by answering the two questions below, in this order.** Neither pattern is right for every application.\n\n1. **How wide are the screens the application supports?** At the tablet breakpoint or wider, a top bar or a sidebar both work. A sidebar is often preferred, because a wide screen has more width than height. Below the tablet breakpoint, never use a sidebar. A sidebar there leaves almost no width for the content. Use a hamburger menu instead.\n2. **How many top-level items are there, and will the number grow?** A top bar fits only a few items, about three or four, that will not grow. For example, Home, Orders and Reports fit a top bar. More items, or items expected to grow, get a sidebar. A sidebar has room to stack the items, and a top bar runs out of width.\n\nTreat three or four items as a default, not a hard limit. If the choice is not obvious, confirm the choice with the user.\n\n## Global tools\n\n**Keep search, notifications, and the user or account menu out of primary navigation.** Search, notifications and the account menu are global tools. A global tool is used everywhere, and is not a destination in the information architecture. Put the global tools in another part of the application chrome (the header, navigation and footer around the content). Global tools in the primary navigation cause two problems:\n\n- The global tools raise the number of navigation items.\n- The global tools mix tools in with the destinations the navigation lists.\n\n## Number of navigation items\n\n**Aim for about 7 ± 2 items per navigation level, adjusted for how complex the subject matter is.** The number is a guideline from psychology, not a hard limit. Use judgment. For example, more items fit when every label is short. Going well past the guideline is a sign that a different pattern or component may fit better.\n\n- **For complex subject matter, aim for about 5 items.**\n- **For simple subject matter, allow up to 9 items.**\n\nSee `recursica-skill-working-memory` for the reasoning, the research, and the limits of the 7 ± 2 guideline.\n\n**Treat too many items as the real defect, and the overflow as the symptom.** A horizontal navigation that runs out of room has almost always gone past 7 ± 2 items first. Keeping to 7 ± 2 items makes the overflow rules possible to enforce.\n\n**If permissions hide navigation items, check the actual number of items for each role, not only the full list.** Each persona then sees a different item count. For example, an admin may see 9 items while a viewer sees 6.\n\n## Exposing sub-levels\n\n**MUST reveal sub-navigation on click, not on hover.** Sub-navigation is the list of items under a navigation item. Clicking a primary navigation item has one of two results, depending on whether the item has a landing page:\n\n- **No landing page:** the navigation expands in place to show the item's sub-navigation, like an accordion. For example, clicking \"Settings\" shows \"Users\" and \"Billing\" under \"Settings\".\n- **Has a landing page:** the click goes to the landing page, and the item's sub-navigation also expands. For example, clicking \"Orders\" opens the Orders page and shows \"Returns\" under \"Orders\".\n\n**Avoid navigation that opens on hover in complex navigation.** Hover causes two problems:\n\n- Personas struggle to steer a mouse across menus that appear on hover.\n- Sub-navigation that opens on hover is much harder to make accessible.\n\nA large number of items may force a mega menu (a large panel that shows many links at once). A mega menu sometimes makes hover unavoidable. Treat hover in that case as a failure of the item count, not as a design option. Prefer sub-navigation that opens on a click and updates the screen.\n\n## Choosing the sub-nav component\n\n**An accordion has one level only, unless the theme (the design a designer sets in Theme Forge: the token values, the components, and each component's variants, states and sizes) has a nesting option.** Without a nesting option, NEVER nest an accordion inside an accordion. If the navigation structure has several levels, use a tree instead.\n\n**Use the simplest structure the content allows.** A plain list of links is a valid answer, and often the right answer. For example, five reports with no groups need only a list of five links. Use an accordion or a tree only when the content has a real hierarchy.\n\n**MUST use semantic HTML** (HTML elements chosen by role, such as a button element for a button). Navigation is a list, ordered or unordered, and must be marked up as a list.\n\n**A top-level item with no sub-navigation MUST stay directly navigable.** The persona can go straight to the item's page. For example, a Dashboard item with no sub-navigation is a link, not an accordion header that does nothing. Navigation often mixes two kinds of item:\n\n- items the persona can go to directly\n- groups that expand\n\nBoth kinds of item must work in the same navigation.\n\n## Default state of collapsible groups\n\n**Every collapsible group MUST start collapsed when the page first loads.** The only group that starts expanded is the group that contains the persona's current page. For example, on the Returns page, only the group that holds \"Returns\" starts expanded.\n\nExpanding every group adds no value. With every group expanded, the group labels at the top level have no reason to exist.\n\n**Group labels must be clear enough that the persona knows which group to expand without opening the group.** For example, \"Billing\" tells the persona what the group holds, and \"Other\" does not. If the group labels are not clear enough, fix the labels instead of expanding the group. Groups that start collapsed depend on clear group labels.\n\n## Indicating location\n\nA screen can show the persona's location in three ways. On every screen, use more than the first way.\n\n1. **A selected state** on the active item. Tree and navigation components provide a selected state. Use the component's selected state. Do not invent a custom selected state.\n2. **Clear page titles that show the hierarchy** through heading levels (H1, H2, and so on).\n3. **Breadcrumbs**, using the breadcrumb component, where the depth of the page calls for breadcrumbs.\n\n**Information on the page itself MUST show the location, whether or not the navigation is visible.** Show the location through headings, breadcrumbs, or both. Never rely on the navigation being on screen as the only answer to \"where am I?\"\n\n## Hiding navigation\n\n**Hiding the navigation entirely behind a hamburger menu or a similar control is acceptable when both conditions below hold:**\n\n- The persona uses the navigation rarely.\n- The screen space is needed.\n\nHidden navigation is not a compromise. For navigation the persona rarely touches, hiding the navigation is correct.\n\n**If the persona moves back and forth between sections, keep the navigation visible at all times.** For example, a persona who switches between Orders and Customers all day needs the navigation in view. At the tablet breakpoint or wider, how often the persona uses the navigation decides whether to hide the navigation.\n\n**NEVER collapse a vertical navigation into a rail of icons only.** A rail of icons is a narrow strip showing icons without labels. When space is needed, hide the navigation behind a hamburger menu that opens with the text labels still in place. A rail of icons has no real benefit. Fully hidden navigation that opens with clear labels beats always-visible navigation the persona has to decode.\n\n**NEVER use icon-only primary navigation**, in any form. The ban on icon-only navigation holds at every width. A rail of icons is not an alternative for mobile or tablet. Icon-only navigation fails for two reasons:\n\n- Beyond a handful of icons, nobody remembers what each icon means.\n- Without a hover state, an icon has no affordance (a visible cue that a control can be used, such as the underline on a link).\n\nOne published design system shows the real-world extreme: a rail of fifteen icons. When the rail collapses, the rail shrinks the icons down to bare dots. The persona must hover over each dot to identify the dot. See `recursica-skill-responsive-layout` and `recursica-skill-icon-semantics`.\n\n**Below the tablet breakpoint, collapse global navigation into a hamburger menu.** The menu that slides in shows both the icon and the text of each navigation item.\n\n**NEVER use a bottom navigation bar.** A bottom navigation bar is not a house pattern at any width. Below the tablet breakpoint, use a hamburger menu instead.\n\n**The navigation drawer is the menu a hamburger button opens, and the drawer is not a panel.** The drawer slides in like a panel, but holds the navigation. The panel rules do not apply to the drawer. A sidebar is the permanent navigation down the left side of the page. A sidebar is the wide-screen alternative to a top navigation bar. See `recursica-skill-panels-modals`.\n\n**Use a drawer or a sidebar for the application's navigation, never both at the same time.** A drawer and a sidebar are both valid choices. Do not add an option to pin the drawer open as a sidebar. Show the navigation or hide the navigation, and keep the choice that simple.\n\n**Confirm with the user which devices, screen sizes and orientations the application supports before choosing the navigation pattern.** Do not add room for tablet or phone use to the navigation after the navigation pattern is chosen. `recursica-skill-responsive-layout` sets this rule.\n\n## Overflow\n\n**NEVER handle overflow in a horizontal navigation. Change the design instead.** Overflow means the items do not fit in the horizontal navigation. Overflow means the design is wrong. Each fix changes the structure:\n\n- Switch to a vertical navigation.\n- Shorten the labels and make the labels more specific. Long, vague labels are a common root cause. For example, \"Customer account management\" becomes \"Accounts\".\n\nNavigation has three hard bans:\n\n- **NEVER wrap horizontal navigation onto a second row.**\n- **NEVER scroll navigation horizontally.** Horizontal navigation must be fully visible at all times. Avoid horizontal scrolling in any part of an enterprise application at almost any cost. In navigation, horizontal scrolling has no valid reason at all.\n- **NEVER put navigation in a separate scrolling area.** Vertical navigation that scrolls _with the page_ is fine. A separate scrolling `div` only for the navigation is not allowed.\n\n**A navigation the persona customizes is the only exception.** An ellipsis or \"More\" control that hides top-level items is acceptable only when both conditions below hold:\n\n- The persona can customize the navigation.\n- The persona chose what to hide.\n\nFor example, the persona moved \"Archive\" into \"More\" in the navigation settings. Without that explicit choice by the persona, no overflow state is acceptable in a horizontal navigation.\n\n## Permissions and unavailable items\n\n**MUST hide any navigation item the persona does not have permission to use.** No permission means no entry in the navigation. For example, a persona without billing access sees no \"Billing\" item.\n\n- Do not show the item disabled.\n- Do not show the item and then fail when the persona clicks the item.\n\n**Disable a navigation item, rather than hide the item, when the persona can fix what makes the item unavailable.** The persona may be able to change the condition that blocks the item. Examples of such a condition:\n\n- a setup step not done yet\n- a missing prerequisite the persona controls\n\nShow the blocked item disabled, and enable the item once the persona makes the change. The test is whether the persona has the power to fix the cause:\n\n- Hide an item the persona can never reach.\n- Disable an item the persona can unlock.\n\n## Tabs\n\n**Use tabs only when the content is parts of one whole.** The persona switches between tabs while looking at the same material. For example, an order's Details, Items and History tabs all describe one order.\n\n**Open the first tab in reading order by default.** In a locale that reads left to right, the first tab is the leftmost tab. The eye starts on the left in such a locale. `recursica-skill-screen-starting-state` sets this rule.\n\n**MUST NOT spread a form across tabs.** Tabs divide content into sections. Tabs never break up data entry. Give a form with several parts a stepper component (which walks the persona through numbered steps), not tabs. Never put the fields of one form, with one save button, on separate tabs. Each tab may hold the tab's own complete form, with the form's own save button. If a tab's form has unsaved changes, confirm with the persona before switching tabs. A panel asks the same way before closing.\n\n**Use the tab component, keep the tab component's behavior, and do not add custom key handling.** The code library under the Recursica tab component decides how the keyboard works inside a set of tabs. For example, the code library decides whether the arrow keys or the Tab key move focus between tabs.\n\n## Open questions\n\n**Confirm with the user instead of choosing.** No house rule covers the topics below yet. See the never-guess rule in `recursica-skill-design-router`. Do not stretch a rule in this skill to fit the topics below.\n\n- **The order of items within a level.** No rule says whether to order items by how often the items are used, alphabetically, or by workflow order.\n- **Maximum depth.** The 7 ± 2 guideline covers the number of items in each level, not how many levels are acceptable.\n- **Whether a dashboard or overview screen gets its own navigation item, and where.**\n\n## Out of scope\n\n- **All color, visual design, and styling.** The Recursica components handle color, visual design and styling.\n- **Keyboard interaction inside a component**: tab sets, trees and menus. The code library under each Recursica component decides the keyboard interaction.\n- **Where global tools go and how global tools behave.** The global tools are search, notifications and the account menu. This skill rules only that global tools stay out of primary navigation.\n- **Form layout, validation, saving, and steppers.** `recursica-skill-forms` covers form layout, validation, saving and steppers. This skill decides _that_ a form with several parts uses a stepper. `recursica-skill-stepper` decides how the stepper behaves.\n- **Storing navigation state as a preference saved for the persona.** Routing covers the navigation state that needs restoring. Any approach beyond routing is a question of how the code is built.\n\n## Pre-flight checklist\n\nCheck every item below before treating the navigation as done.\n\n- [ ] The application uses a drawer or a sidebar for navigation, not both at once.\n- [ ] The application has no option to pin the drawer open.\n- [ ] Every view the persona can navigate to has its own route, reachable by URL.\n- [ ] Navigation adds entries to the browser history, and back and forward work correctly.\n- [ ] No modal or panel creates a history entry. Every panel, modal and tab has an address whenever possible. A confirmation modal has none.\n- [ ] No tab state is kept as remembered UI state in place of a route.\n- [ ] Each tab has its own sub-path under the route of the view that holds the tabs.\n- [ ] A top bar holds only a few items, about three or four, that will not grow. More items, or items expected to grow, get a sidebar. No sidebar appears below the tablet breakpoint.\n- [ ] The navigation is vertical where top-level items will grow.\n- [ ] Each level holds about 7 ± 2 items, judged by label length and how complex the subject is.\n- [ ] The item count holds for each role, after permissions hide items.\n- [ ] Search, notifications, and the account menu are outside primary navigation.\n- [ ] Sub-navigation opens on click, not on hover.\n- [ ] Clicking a primary item that has a landing page goes to the landing page and expands the item's sub-navigation.\n- [ ] Clicking a primary item without a landing page expands the item in place.\n- [ ] No accordion is nested inside another accordion unless the theme has a nesting option.\n- [ ] Navigation structures with several levels use a tree.\n- [ ] Navigation is marked up as a semantic ordered or unordered list.\n- [ ] Top-level items with no sub-navigation are links the persona can go to directly.\n- [ ] Collapsible groups load collapsed, except the group containing the current page.\n- [ ] Group labels are specific enough to choose between while the groups are collapsed.\n- [ ] The active item uses the component's selected state.\n- [ ] The page itself shows the location through the page's heading hierarchy, breadcrumbs, or both.\n- [ ] Navigation is hidden only where the navigation is used rarely, and stays visible where personas move between sections.\n- [ ] The navigation has no icon-only rail and no icon-only primary navigation. Hidden navigation opens with text labels.\n- [ ] Items the persona has no permission for are missing, not disabled.\n- [ ] Items blocked by a condition the persona controls are disabled, and become enabled once the condition is fixed.\n- [ ] Horizontal navigation does not wrap, does not scroll, and does not sit in a separate scrolling area.\n- [ ] There is no overflow control, unless the persona can customize the navigation and chose to hide items.\n- [ ] Tabs hold parts of one whole. No form spreads across tabs, and each form on a tab has the form's own save button.\n- [ ] Switching away from a tab with unsaved changes asks the persona first.\n- [ ] Tab sets have no custom keyboard handling.\n- [ ] Forms with several parts use a stepper.\n- [ ] Open questions were asked about, not decided: the order of items, the maximum depth, and where a dashboard goes.\n","# Navigation and tabs\n\nThis skill holds the house rules for the navigation of an application. The rules cover:\n\n- primary and secondary navigation\n- showing the items under a navigation item\n- showing the persona where the persona is\n- overflow\n- routes and the browser history\n- tabs\n\nTreat each rule as a constraint. The rules are opinions, not neutral best practices.\n\nThe rules assume **complex enterprise web applications, designed for desktop first**, built on the Recursica design system. The design system decides how each component looks, including selected states, hover styling, spacing and color. This skill decides the structure, the interaction, and how routes behave.\n\n**Never build a control that moves the persona to a new place and does a second action in one click.** Each of the following is a separate outcome:\n\n- moving the persona to a new place\n- applying a filter\n- opening a region that holds content, such as a page, a panel or a modal\n- switching a tab\n\nWhen one click has two of the outcomes above, the control's label can honestly describe only one outcome.\n\n**If a destination must open already filtered, make the filtered view a separate destination with a separate route.** For example, a \"Late orders\" view gets a route separate from the Orders page. A \"Late orders\" link goes to that route, and the link itself applies no filter. See convention 6 in `recursica-skill-design-system-conventions`.\n\n**Make each navigation label name an object, not an action.** Write `Forms`, never `View forms`. `recursica-skill-names-and-terms` decides three questions about each navigation label:\n\n- what each item is called\n- whether a name is singular or plural\n- how much a term may be shortened\n\n## Governing principles\n\n1. **Make every location a route.** Give each place the persona navigates to a separate URL and an entry in the browser history. A modal or a panel that a trigger opens gets a URL whenever possible, but no history entry. The route rule is the most important rule in this skill, because designs break the route rule most often.\n2. **Fix the information architecture instead of working around the information architecture.** Information architecture is how the application's content is organized and labeled. `recursica-skill-information-architecture` sets the rules for information architecture. Each of the following is a symptom of a mistake in the information architecture:\n\n   - navigation that overflows, wraps or scrolls\n   - forms spread across tabs\n\n   Do not add a workaround to cope with the mistake.\n\n3. **The page itself must show where the persona is**, not only the navigation. Show the location with headings, breadcrumbs, or both. A selected state alone is not enough.\n\n## Routing and browser history\n\n**MUST give every view the persona can navigate to a separate route, reachable by the view's URL.** For example, the Orders page opens when the persona enters the Orders page's URL. Moving between views MUST add an entry to the browser history, so that the back and forward buttons work correctly. Designs break the route and history rule constantly. A missing route or history entry is a serious failure, not a finishing touch.\n\n**MUST NOT create history entries for modals or panels.** A trigger, such as a button, opens a modal or a panel. The persona does not navigate to a modal or a panel. The browser history should record the difference between a place in the application and a temporary state. A history entry for a modal or a panel erases that difference.\n\n**Give every panel, modal and tab an address whenever possible.** An address is a URL that opens the view with the panel, modal or tab already open. For example, a persona sends a coworker a link that opens the Orders page with one order's panel open. An address and a history entry are separate. Opening a panel or a modal changes the address, but adds no history entry.\n\n**A confirmation modal gets no address.** For example, \"Delete this invoice?\" has no URL. A link that opens a confirmation makes no sense. See `recursica-skill-panels-modals`.\n\nApply the routing and history rules equally to moving through primary navigation, secondary navigation and tabs.\n\n**Give each tab a separate route.** Give each tab a sub-path under the route of the view that holds the tabs. For example, an order page at `\u002Forders\u002F1042` puts the History tab at `\u002Forders\u002F1042\u002Fhistory`. A tab with a route can be linked to, restored, and reached with back and forward like any other location.\n\n**Restore a layout through routing, not through a remembered preference.** Do not build \"remember which tab was open\" as stored UI state. When each tab is a route, going back to a tab's URL restores the tab, and the back button works. Any approach beyond routing is a question of how the code is built, not a design decision.\n\n**Put the navigation on layer 0 beside the main content, unless the navigation or the main content needs containing.** A layer is a numbered background level, 0 to 3, that sets the colors of the components on that level. Layer 0 is the page itself.\n\n- Confirm with the user whether the navigation or the main content needs containing.\n- If containing is wanted, raise either the navigation or the main content to layer 1, not both.\n- Keep the same choice across the whole application.\n\n`recursica-skill-layers` sets the layer rules.\n\n## Horizontal top bar vs. vertical sidebar\n\n**Choose between a top bar and a sidebar by answering the two questions below, in this order.** Neither pattern is right for every application.\n\n1. **How wide are the screens the application supports?** At the tablet breakpoint or wider, a top bar or a sidebar both work. A sidebar is often preferred, because a wide screen has more width than height. Below the tablet breakpoint, never use a sidebar. A sidebar there leaves almost no width for the content. Use a hamburger menu instead.\n2. **How many top-level items are there, and will the number grow?** A top bar fits only a few items, about three or four, that will not grow. For example, Home, Orders and Reports fit a top bar. More items, or items expected to grow, get a sidebar. A sidebar has room to stack the items, and a top bar runs out of width.\n\nTreat three or four items as a default, not a hard limit. If the choice is not obvious, confirm the choice with the user.\n\n## Global tools\n\n**Keep search, notifications, and the user or account menu out of primary navigation.** Search, notifications and the account menu are global tools. A global tool is used everywhere, and is not a destination in the information architecture. Put the global tools in another part of the application chrome (the header, navigation and footer around the content). Global tools in the primary navigation cause two problems:\n\n- The global tools raise the number of navigation items.\n- The global tools mix tools in with the destinations the navigation lists.\n\n## Number of navigation items\n\n**Aim for about 7 ± 2 items per navigation level, adjusted for how complex the subject matter is.** The number is a guideline from psychology, not a hard limit. Use judgment. For example, more items fit when every label is short. Going well past the guideline is a sign that a different pattern or component may fit better.\n\n- **For complex subject matter, aim for about 5 items.**\n- **For simple subject matter, allow up to 9 items.**\n\nSee `recursica-skill-working-memory` for the reasoning, the research, and the limits of the 7 ± 2 guideline.\n\n**Treat too many items as the real defect, and the overflow as the symptom.** A horizontal navigation that runs out of room has almost always gone past 7 ± 2 items first. Keeping to 7 ± 2 items makes the overflow rules possible to enforce.\n\n**If permissions hide navigation items, check the actual number of items for each role, not only the full list.** Each persona then sees a different item count. For example, an admin may see 9 items while a viewer sees 6.\n\n## Exposing sub-levels\n\n**MUST reveal sub-navigation on click, not on hover.** Sub-navigation is the list of items under a navigation item. Clicking a primary navigation item has one of two results, depending on whether the item has a landing page:\n\n- **No landing page:** the navigation expands in place to show the item's sub-navigation, like an accordion. For example, clicking \"Settings\" shows \"Users\" and \"Billing\" under \"Settings\".\n- **Has a landing page:** the click goes to the landing page, and the item's sub-navigation also expands. For example, clicking \"Orders\" opens the Orders page and shows \"Returns\" under \"Orders\".\n\n**Avoid navigation that opens on hover in complex navigation.** Hover causes two problems:\n\n- Personas struggle to steer a mouse across menus that appear on hover.\n- Sub-navigation that opens on hover is much harder to make accessible.\n\nA large number of items may force a mega menu (a large panel that shows many links at once). A mega menu sometimes makes hover unavoidable. Treat hover in that case as a failure of the item count, not as a design option. Prefer sub-navigation that opens on a click and updates the screen.\n\n## Choosing the sub-nav component\n\n**An accordion has one level only, unless the theme (the design a designer sets in Theme Forge: the token values, the components, and each component's variants, states and sizes) has a nesting option.** Without a nesting option, NEVER nest an accordion inside an accordion. If the navigation structure has several levels, use a tree instead.\n\n**Use the simplest structure the content allows.** A plain list of links is a valid answer, and often the right answer. For example, five reports with no groups need only a list of five links. Use an accordion or a tree only when the content has a real hierarchy.\n\n**MUST use semantic HTML** (HTML elements chosen by role, such as a button element for a button). Navigation is a list, ordered or unordered, and must be marked up as a list.\n\n**A top-level item with no sub-navigation MUST stay directly navigable.** The persona can go straight to the item's page. For example, a Dashboard item with no sub-navigation is a link, not an accordion header that does nothing. Navigation often mixes two kinds of item:\n\n- items the persona can go to directly\n- groups that expand\n\nBoth kinds of item must work in the same navigation.\n\n## Default state of collapsible groups\n\n**Every collapsible group MUST start collapsed when the page first loads.** The only group that starts expanded is the group that contains the persona's current page. For example, on the Returns page, only the group that holds \"Returns\" starts expanded.\n\nExpanding every group adds no value. With every group expanded, the group labels at the top level have no reason to exist.\n\n**Group labels must be clear enough that the persona knows which group to expand without opening the group.** For example, \"Billing\" tells the persona what the group holds, and \"Other\" does not. If the group labels are not clear enough, fix the labels instead of expanding the group. Groups that start collapsed depend on clear group labels.\n\n## Indicating location\n\nA screen can show the persona's location in three ways. On every screen, use more than the first way.\n\n1. **A selected state** on the active item. Tree and navigation components provide a selected state. Use the component's selected state. Do not invent a custom selected state.\n2. **Clear page titles that show the hierarchy** through heading levels (H1, H2, and so on).\n3. **Breadcrumbs**, using the breadcrumb component, where the depth of the page calls for breadcrumbs.\n\n**Information on the page itself MUST show the location, whether or not the navigation is visible.** Show the location through headings, breadcrumbs, or both. Never rely on the navigation being on screen as the only answer to \"where am I?\"\n\n## Hiding navigation\n\n**Hiding the navigation entirely behind a hamburger menu or a similar control is acceptable when both conditions below hold:**\n\n- The persona uses the navigation rarely.\n- The screen space is needed.\n\nHidden navigation is not a compromise. For navigation the persona rarely touches, hiding the navigation is correct.\n\n**If the persona moves back and forth between sections, keep the navigation visible at all times.** For example, a persona who switches between Orders and Customers all day needs the navigation in view. At the tablet breakpoint or wider, how often the persona uses the navigation decides whether to hide the navigation.\n\n**NEVER collapse a vertical navigation into a rail of icons only.** A rail of icons is a narrow strip showing icons without labels. When space is needed, hide the navigation behind a hamburger menu that opens with the text labels still in place. A rail of icons has no real benefit. Fully hidden navigation that opens with clear labels beats always-visible navigation the persona has to decode.\n\n**NEVER use icon-only primary navigation**, in any form. The ban on icon-only navigation holds at every width. A rail of icons is not an alternative for mobile or tablet. Icon-only navigation fails for two reasons:\n\n- Beyond a handful of icons, nobody remembers what each icon means.\n- Without a hover state, an icon has no affordance (a visible cue that a control can be used, such as the underline on a link).\n\nOne published design system shows the real-world extreme: a rail of fifteen icons. When the rail collapses, the rail shrinks the icons down to bare dots. The persona must hover over each dot to identify the dot. See `recursica-skill-responsive-layout` and `recursica-skill-icon-semantics`.\n\n**Below the tablet breakpoint, collapse global navigation into a hamburger menu.** The menu that slides in shows both the icon and the text of each navigation item.\n\n**NEVER use a bottom navigation bar.** A bottom navigation bar is not a house pattern at any width. Below the tablet breakpoint, use a hamburger menu instead.\n\n**The navigation drawer is the menu a hamburger button opens, and the drawer is not a panel.** The drawer slides in like a panel, but holds the navigation. The panel rules do not apply to the drawer. A sidebar is the permanent navigation down the left side of the page. A sidebar is the wide-screen alternative to a top navigation bar. See `recursica-skill-panels-modals`.\n\n**Use a drawer or a sidebar for the application's navigation, never both at the same time.** A drawer and a sidebar are both valid choices. Do not add an option to pin the drawer open as a sidebar. Show the navigation or hide the navigation, and keep the choice that simple.\n\n**Confirm with the user which devices, screen sizes and orientations the application supports before choosing the navigation pattern.** Do not add room for tablet or phone use to the navigation after the navigation pattern is chosen. `recursica-skill-responsive-layout` sets this rule.\n\n## Overflow\n\n**NEVER handle overflow in a horizontal navigation. Change the design instead.** Overflow means the items do not fit in the horizontal navigation. Overflow means the design is wrong. Each fix changes the structure:\n\n- Switch to a vertical navigation.\n- Shorten the labels and make the labels more specific. Long, vague labels are a common root cause. For example, \"Customer account management\" becomes \"Accounts\".\n\nNavigation has three hard bans:\n\n- **NEVER wrap horizontal navigation onto a second row.**\n- **NEVER scroll navigation horizontally.** Horizontal navigation must be fully visible at all times. Avoid horizontal scrolling in any part of an enterprise application at almost any cost. In navigation, horizontal scrolling has no valid reason at all.\n- **NEVER put navigation in a separate scrolling area.** Vertical navigation that scrolls _with the page_ is fine. A separate scrolling `div` only for the navigation is not allowed.\n\n**A navigation the persona customizes is the only exception.** An ellipsis or \"More\" control that hides top-level items is acceptable only when both conditions below hold:\n\n- The persona can customize the navigation.\n- The persona chose what to hide.\n\nFor example, the persona moved \"Archive\" into \"More\" in the navigation settings. Without that explicit choice by the persona, no overflow state is acceptable in a horizontal navigation.\n\n## Permissions and unavailable items\n\n**MUST hide any navigation item the persona does not have permission to use.** No permission means no entry in the navigation. For example, a persona without billing access sees no \"Billing\" item.\n\n- Do not show the item disabled.\n- Do not show the item and then fail when the persona clicks the item.\n\n**Disable a navigation item, rather than hide the item, when the persona can fix what makes the item unavailable.** The persona may be able to change the condition that blocks the item. Examples of such a condition:\n\n- a setup step not done yet\n- a missing prerequisite the persona controls\n\nShow the blocked item disabled, and enable the item once the persona makes the change. The test is whether the persona has the power to fix the cause:\n\n- Hide an item the persona can never reach.\n- Disable an item the persona can unlock.\n\n## Tabs\n\n**Use tabs only when the content is parts of one whole.** The persona switches between tabs while looking at the same material. For example, an order's Details, Items and History tabs all describe one order.\n\n**Open the first tab in reading order by default.** In a locale that reads left to right, the first tab is the leftmost tab. The eye starts on the left in such a locale. `recursica-skill-screen-starting-state` sets this rule.\n\n**MUST NOT spread a form across tabs.** Tabs divide content into sections. Tabs never break up data entry. Give a form with several parts a stepper component (which walks the persona through numbered steps), not tabs. Never put the fields of one form, with one save button, on separate tabs. Each tab may hold the tab's own complete form, with the form's own save button. If a tab's form has unsaved changes, confirm with the persona before switching tabs. A panel asks the same way before closing.\n\n**Use the tab component, keep the tab component's behavior, and do not add custom key handling.** The code library under the Recursica tab component decides how the keyboard works inside a set of tabs. For example, the code library decides whether the arrow keys or the Tab key move focus between tabs.\n\n## Open questions\n\n**Confirm with the user instead of choosing.** No house rule covers the topics below yet. See the never-guess rule in `recursica-skill-design-router`. Do not stretch a rule in this skill to fit the topics below.\n\n- **The order of items within a level.** No rule says whether to order items by how often the items are used, alphabetically, or by workflow order.\n- **Maximum depth.** The 7 ± 2 guideline covers the number of items in each level, not how many levels are acceptable.\n- **Whether a dashboard or overview screen gets its own navigation item, and where.**\n\n## Out of scope\n\n- **All color, visual design, and styling.** The Recursica components handle color, visual design and styling.\n- **Keyboard interaction inside a component**: tab sets, trees and menus. The code library under each Recursica component decides the keyboard interaction.\n- **Where global tools go and how global tools behave.** The global tools are search, notifications and the account menu. This skill rules only that global tools stay out of primary navigation.\n- **Form layout, validation, saving, and steppers.** `recursica-skill-forms` covers form layout, validation, saving and steppers. This skill decides _that_ a form with several parts uses a stepper. `recursica-skill-stepper` decides how the stepper behaves.\n- **Storing navigation state as a preference saved for the persona.** Routing covers the navigation state that needs restoring. Any approach beyond routing is a question of how the code is built.\n\n## Pre-flight checklist\n\nCheck every item below before treating the navigation as done.\n\n- [ ] The application uses a drawer or a sidebar for navigation, not both at once.\n- [ ] The application has no option to pin the drawer open.\n- [ ] Every view the persona can navigate to has its own route, reachable by URL.\n- [ ] Navigation adds entries to the browser history, and back and forward work correctly.\n- [ ] No modal or panel creates a history entry. Every panel, modal and tab has an address whenever possible. A confirmation modal has none.\n- [ ] No tab state is kept as remembered UI state in place of a route.\n- [ ] Each tab has its own sub-path under the route of the view that holds the tabs.\n- [ ] A top bar holds only a few items, about three or four, that will not grow. More items, or items expected to grow, get a sidebar. No sidebar appears below the tablet breakpoint.\n- [ ] The navigation is vertical where top-level items will grow.\n- [ ] Each level holds about 7 ± 2 items, judged by label length and how complex the subject is.\n- [ ] The item count holds for each role, after permissions hide items.\n- [ ] Search, notifications, and the account menu are outside primary navigation.\n- [ ] Sub-navigation opens on click, not on hover.\n- [ ] Clicking a primary item that has a landing page goes to the landing page and expands the item's sub-navigation.\n- [ ] Clicking a primary item without a landing page expands the item in place.\n- [ ] No accordion is nested inside another accordion unless the theme has a nesting option.\n- [ ] Navigation structures with several levels use a tree.\n- [ ] Navigation is marked up as a semantic ordered or unordered list.\n- [ ] Top-level items with no sub-navigation are links the persona can go to directly.\n- [ ] Collapsible groups load collapsed, except the group containing the current page.\n- [ ] Group labels are specific enough to choose between while the groups are collapsed.\n- [ ] The active item uses the component's selected state.\n- [ ] The page itself shows the location through the page's heading hierarchy, breadcrumbs, or both.\n- [ ] Navigation is hidden only where the navigation is used rarely, and stays visible where personas move between sections.\n- [ ] The navigation has no icon-only rail and no icon-only primary navigation. Hidden navigation opens with text labels.\n- [ ] Items the persona has no permission for are missing, not disabled.\n- [ ] Items blocked by a condition the persona controls are disabled, and become enabled once the condition is fixed.\n- [ ] Horizontal navigation does not wrap, does not scroll, and does not sit in a separate scrolling area.\n- [ ] There is no overflow control, unless the persona can customize the navigation and chose to hide items.\n- [ ] Tabs hold parts of one whole. No form spreads across tabs, and each form on a tab has the form's own save button.\n- [ ] Switching away from a tab with unsaved changes asks the persona first.\n- [ ] Tab sets have no custom keyboard handling.\n- [ ] Forms with several parts use a stepper.\n- [ ] Open questions were asked about, not decided: the order of items, the maximum depth, and where a dashboard goes.\n",{"name":5,"license":15,"metadata":24,"description":7},{"author":25,"version":26},"hi@borderux.com","0.2.0","main","110b382bfe525d171ba33c7074d6ad1f3762548f","skills\u002Fdesign-rules\u002Frecursica-skill-navigation",0,"https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge","https:\u002F\u002Fgithub.com\u002Fborderux","https:\u002F\u002Fborderux.com","2026-11-09 16:39:27",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add borderux\u002Frecursica-knowledge --skill recursica-skill-navigation",{"tool":41,"command":42},"bunx","bunx skills add borderux\u002Frecursica-knowledge --skill recursica-skill-navigation",{"tool":44,"command":45},"pnpm","pnpm dlx skills add borderux\u002Frecursica-knowledge --skill recursica-skill-navigation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge\u002Fblob\u002Fmain\u002Fskills\u002Fdesign-rules\u002Frecursica-skill-navigation\u002FSKILL.md",true,[],[50,58,65,72,79,86],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":54,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":19},"01M7556E67F3DCE39P7ZTVT5TA","recursica-skill-template","Replace with a description of the skill and its purpose.","https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge\u002Fblob\u002Fmain\u002Ftemplate\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge\u002Fblob\u002Fmain\u002Ftemplate\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M75569FCJXWWGXRVMTJFBK0W","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.","https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge\u002Fblob\u002Fmain\u002Fskills\u002Fpsychology\u002Frecursica-skill-working-memory\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M75564EC5E5QKBPNWARQVDBC","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.","https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge\u002Fblob\u002Fmain\u002Fskills\u002Fpsychology\u002Frecursica-skill-discoverability\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M7555Z2YRG9YSM01KMYT1FY5","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.","https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge\u002Fblob\u002Fmain\u002Fskills\u002Fmeta\u002Frecursica-skill-design-router\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M7555RYHBH6XM48V2420Z66X","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.","https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge\u002Fblob\u002Fmain\u002Fskills\u002Fdesign-rules\u002Frecursica-skill-undo\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M7555K4E6TKJ9E9P7GCQYJZ8","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.","https:\u002F\u002Fgithub.com\u002Fborderux\u002Frecursica-knowledge\u002Fblob\u002Fmain\u002Fskills\u002Fdesign-rules\u002Frecursica-skill-typography-semantics\u002FSKILL.md",[],[]]