AnatomyLink to the section Anatomy
The SidebarRail has four parts. The rail is 72 px wide, with an icon and a short label per section. The side panel is 240 px wide and lists the pages of the open section under plain headings. A page with children is a row with a chevron, and its pages open in a flyout, also 240 px wide, further to the side and lined up with the row; a third level opens the same way. Nothing ever expands downward. The site or workspace switcher sits on top of the rail; the theme and the user menu sit at the bottom.
The demo below is docked and stands on Commerce, Products, Variants, so the path to the open page is highlighted through every level. Point at Products, or press Enter on it, to see the flyout.
<SidebarRail
sections={[
{
id: 'commerce',
label: 'Commerce',
icon: <Icon name="content.product" />,
groups: [
{
label: 'Sales',
links: [
{
href: '/products',
label: 'Products',
children: [
{ href: '/products/variants', label: 'Variants' },
{ href: '/products/brands', label: 'Brands' }
]
}
]
}
]
}
]}
current={pathname}
labels={labels}
storageKey="content"
top={<SiteSwitcher />}
bottom={
<>
<ThemeMenu />
<UserMenu />
</>
}
/>The cascade to the sideLink to the section The cascade to the side
- The rail opens the panel at
72px from the start edge, a flyout opens at312px, and a third level at552px. Each overlaps the border before it by 1 px. - The top of a flyout is lined up with the top of the row that opened it, and moves up only as far as it needs to stay inside the sidebar. A taller flyout scrolls inside.
- Opening a level never moves a row of the level that holds its parent.
- Hover intent: with a mouse, a section or a row opens its level after 150 ms of hovering, so a pointer passing over the rows does not flash levels open.
- Safe triangle: while a deeper level is open, moving the pointer diagonally towards it does not switch to the rows it crosses on the way. The switch waits about 300 ms and is cancelled once the pointer enters the level.
- A floating panel and all flyouts close on a click outside, on Esc, when the pointer leaves the whole sidebar, and on a choice of a page.
On a phoneLink to the section On a phone
Below 48rem there are no flyouts. The menu button opens one modal drawer whose levels are screens: the sections first, then a section, then the children of a row. A new screen slides in from the side, and every screen but the first starts with a back row that says where it returns to, such as “Back to Commerce”, set by labels.backTo. The drawer opens on the screen of the open page.
StatesLink to the section States
| State | Behaviour |
|---|---|
| Compact (default) | Only the 72 px rail shows and the content has the full width. Pick a section to open its panel. |
| Floating panel | A section opens its 240 px panel to the side of the rail, over the content. It opens on a click, Enter, Space or the right arrow, and previews after a 150 ms mouse hover. It closes on a click outside, Esc or a choice of a page. |
| Docked | The pin button in the panel header docks the panel beside the content, and it keeps its place. The round button on the edge of the sidebar, or the [ key, folds it back to the rail and docks it again; the content slides along over 180 ms. The choice and the last section are remembered under the storageKey. Flyouts still float. |
| Second level | A page with children is a row with a chevron. It opens a 240 px flyout further to the side of the panel, with its top lined up with the row. The flyout starts with a link to the parent page. |
| Third level | A row of a flyout may have children too, and they open one more flyout to the side the same way. A fourth level is not supported. |
| Phone drawer | Below 48rem the rail becomes one modal drawer behind the menu button. Each level is a screen that slides in from the side, with a back row named by labels.backTo, such as "Back to Commerce". Nothing expands in place. |
The six standard groupsLink to the section The six standard groups
Every app uses these groups, in this order, so a person who knows one Skribly app finds the same places in the next. An app leaves out the groups it has no features for; it never renames them or reorders them.
| Group | Icon | What belongs in it |
|---|---|---|
| Home | nav.home | The landing page of the app: a summary, what needs attention, shortcuts. A plain link, with no panel. |
| Content | file.document | What the app holds and the user writes or edits: pages, posts, media, projects, documents. |
| Commerce | content.product | Anything that is sold or fulfilled: products, orders, customers, returns. Leave it out of apps with no such features. |
| Marketing | ai.sparkles | Reaching people: newsletters, campaigns, search appearance, social posts. |
| Insights | nav.analytics | Reading how things go: overview, traffic, reports, logs. |
| Settings | nav.settings | Configuration of the app or site: general, integrations, members and roles, billing, advanced. |
How each app maps its sections
An app keeps its own words for pages and features, and places them under the closest group. Where a group does not fit, the rail simply has no such button.
| App | Home | Content | Commerce | Marketing | Insights | Settings |
|---|---|---|---|---|---|---|
| Agent (desktop app) | Home | Skills, sessions | None | None | Run history, usage | Models, folders, account |
| Content panel | Home | Pages, posts, media | Orders, products (when enabled) | Newsletter, search appearance | Traffic, reports | Site, members, integrations |
| Tracker | Home | Projects, issues, boards | None | None | Burndown, velocity, reports | Workspace, members, labels |
| Hub | Home | Apps, projects | None | None | Activity of the apps | Account, team, tokens |
| Id | Home | None | None | None | Sign-in activity | Profile, sign-in, devices |
IconsLink to the section Icons
- Icons come from the registry only:
<Icon name="nav.home" />. See.docs/how-to/use-icons.md. - Three tones, set by the rail itself, so you pass a plain
Icon: rail icons arebrand, the icon of the current section isduo, panel link icons aremonoand the icon of the current link isbrand. - The current item also has a filled pill and a heavier label, so it never depends on colour alone.
{ id: 'commerce', label: 'Commerce', icon: <Icon name="content.product" /> }
{ href: '/orders', label: 'Orders', icon: <Icon name="nav.inbox" /> }Counts and badgesLink to the section Counts and badges
Sections and links take a count and a countLabel. A screen reader hears the label as words, for example “Orders, 4 new”, never a bare number. The number is shown as a badge, and it is never the only signal: the words carry the meaning, not the colour.
{ href: '/orders', label: 'Orders', count: 4, countLabel: '4 new' }Keyboard and screen readerLink to the section Keyboard and screen reader
| Where | Keys | What happens |
|---|---|---|
| Rail | Up, Down, Home, End | Move between the rail buttons. Focus does not wrap. |
| Rail | Enter, Space or Right | Open the panel of the section and move focus to the open page, or to the first link. |
| Panel or flyout | Right, Enter or Space on a row with a chevron | Open its side level and move focus to the first link of that level. |
| Panel or flyout | Left or Esc | Close this level and return focus to the row or the rail button that opened it. Esc on the rail closes a floating panel. |
| Panel or flyout | Up, Down, Home, End | Move between the links inside one level, and from the filter field to the first link. |
| Panel | Type in the filter field | Narrows the links by label and keywords; accents are ignored. An empty result is announced. |
| Page | [ | Fold the docked panel to the rail, or dock it again. It works outside text fields; the button on the edge of the sidebar does the same and shows the key in its tooltip. The choice is remembered. |
| Page | Tab | Order: skip links (to the navigation and to the content), the rail buttons, the open level, the content. Each rail button is a Tab stop; the arrow keys are the faster way between them, and the skip link jumps past the rail. |
- The rail is a named navigation of buttons. Each section button has
aria-expandedandaria-controlsfor its panel. - A row with children is a button with
aria-expanded,aria-controlsandaria-haspopup; its chevron is decorative. A flyout is a navigation named by its title. - Only the open page has
aria-current="page"; the rows on the way to it take the accent tone and say nothing extra. - The panel is a navigation named by its title. The open page has
aria-current="page". - With
hideLabelsthe words under the icons are hidden, and each button shows its label as a tooltip. - Every target is at least 44 px.
MotionLink to the section Motion
A floating panel and every flyout slide 8 px and fade in for 180 ms (--sk-duration-hover), and a phone screen slides in over the same time. Under reduced motion they appear and disappear with no movement.
In a desktop appLink to the section In a desktop app
In an Electron window with a hidden title bar, desktop="mac", "windows" or "linux" leaves a draggable strip over the rail and the panel: 52 px on macOS, for the traffic lights, and 32 px elsewhere. titleBarHeight sets another height. The grey dots in the demo stand for the traffic lights.
<SidebarRail desktop="mac" hideLabels sections={sections} current={pathname} labels={labels} />
// main process: new BrowserWindow({ titleBarStyle: 'hiddenInset' })Do and don’tLink to the section Do and don’t
Orders
Orders and fulfilment
Commerce, Products, then Variants in a flyout to the side
Products with Variants listed below it
Plain headings: Sales, Catalog
A Catalog heading that collapses
Commerce, Products, Variants, then tabs for the rest
Commerce, Products, Variants, Options, Values
A filled pill, a heavier label and aria-current
Only a different colour
Switcher, theme and user menu
A “New order” button in the rail
Adoption checklistLink to the section Adoption checklist
- Sections are mapped to the six groups, in the standard order, and the groups the app does not need are left out.
- Every icon is a registry name through Icon, in the three tones.
- Labels, the labels prop, aria-labels and countLabel are props in English and Polish, with nothing built into the app shell.
- Counts have a countLabel that reads as words.
- storageKey is set per app, so apps on one domain do not share a choice.
- The Agent passes desktop and a title bar matching its window setting.
- Deeper pages open to the side as children of their parent row: no list expands downward, no group collapses, and there is no fourth level.
- Every parent row has its own page, and labels.backTo is set so the phone drawer names where each back row returns to.
- The Laravel panel follows .docs/how-to/adopt-the-sidebar.md.