Skip to content

Patterns

Sidebar

One sidebar for every Skribly app: the Agent desktop app, the content panel, Tracker, Hub and Id. A narrow rail of sections, a panel of their pages and flyouts that open to the side, never downward, built to WCAG 2.2 AA as a target.

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.

Docked: rail, panel and the flyout of Products
Skip to contentSkip to navigation

Variants

Pages with a chevron open one level further to the side.

tsx
<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 72 px from the start edge, a flyout opens at 312 px, and a third level at 552 px. 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.
Compact by default: point at Commerce, then at Products
Skip to contentSkip to navigation

Variants

Pages with a chevron open one level further to the side.

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.

A 24 rem frame: open the menu
Skip to contentSkip to navigation

Variants

Pages with a chevron open one level further to the side.

StatesLink to the section States

The six states of the sidebar
StateBehaviour
Compact (default)Only the 72 px rail shows and the content has the full width. Pick a section to open its panel.
Floating panelA 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.
DockedThe 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 levelA 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 levelA 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 drawerBelow 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.

The six groups, their registry icon and what belongs in each
GroupIconWhat belongs in it
Homenav.homeThe landing page of the app: a summary, what needs attention, shortcuts. A plain link, with no panel.
Contentfile.documentWhat the app holds and the user writes or edits: pages, posts, media, projects, documents.
Commercecontent.productAnything that is sold or fulfilled: products, orders, customers, returns. Leave it out of apps with no such features.
Marketingai.sparklesReaching people: newsletters, campaigns, search appearance, social posts.
Insightsnav.analyticsReading how things go: overview, traffic, reports, logs.
Settingsnav.settingsConfiguration 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.

Which pages of each app go under which group
AppHomeContentCommerceMarketingInsightsSettings
Agent (desktop app)HomeSkills, sessionsNoneNoneRun history, usageModels, folders, account
Content panelHomePages, posts, mediaOrders, products (when enabled)Newsletter, search appearanceTraffic, reportsSite, members, integrations
TrackerHomeProjects, issues, boardsNoneNoneBurndown, velocity, reportsWorkspace, members, labels
HubHomeApps, projectsNoneNoneActivity of the appsAccount, team, tokens
IdHomeNoneNoneNoneSign-in activityProfile, 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 are brand, the icon of the current section is duo, panel link icons are mono and the icon of the current link is brand.
  • The current item also has a filled pill and a heavier label, so it never depends on colour alone.
tsx
{ 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.

tsx
{ href: '/orders', label: 'Orders', count: 4, countLabel: '4 new' }

Keyboard and screen readerLink to the section Keyboard and screen reader

The keyboard map of the sidebar
WhereKeysWhat happens
RailUp, Down, Home, EndMove between the rail buttons. Focus does not wrap.
RailEnter, Space or RightOpen the panel of the section and move focus to the open page, or to the first link.
Panel or flyoutRight, Enter or Space on a row with a chevronOpen its side level and move focus to the first link of that level.
Panel or flyoutLeft or EscClose 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 flyoutUp, Down, Home, EndMove between the links inside one level, and from the filter field to the first link.
PanelType in the filter fieldNarrows 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.
PageTabOrder: 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-expanded and aria-controls for its panel.
  • A row with children is a button with aria-expanded, aria-controls and aria-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 hideLabels the 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.

desktop="mac" with hideLabels
Skip to contentSkip to navigation

Variants

Pages with a chevron open one level further to the side.

tsx
<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

Do. Keep labels to one word, so they fit under the icon in 72 px.

Orders and fulfilment

Don’t. Use a long label that wraps or is cut off.

Commerce, Products, then Variants in a flyout to the side

Do. Open deeper pages to the side, in a flyout lined up with the row.

Products with Variants listed below it

Don’t. Expand a list downward under its parent.

Plain headings: Sales, Catalog

Do. Group links under plain headings that are always shown.

A Catalog heading that collapses

Don’t. Collapse groups.

Commerce, Products, Variants, then tabs for the rest

Do. Stop at three levels, and move anything deeper into tabs in the page header.

Commerce, Products, Variants, Options, Values

Don’t. Nest a fourth level.

A filled pill, a heavier label and aria-current

Do. Mark the current item by shape, weight and aria-current.

Only a different colour

Don’t. Mark the current item with colour alone.

Switcher, theme and user menu

Do. Keep the rail for navigation, plus the switcher, the theme and the user menu.

A “New order” button in the rail

Don’t. Put actions that are not navigation 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.

Search this site

Arrows move through the results, Enter opens one, Esc closes. Ctrl K /