Layout & Navigation

Five sidebar navigation variants, header navigation, mobile responsive patterns, and the theme system. These building blocks define the application shell.

Sidebar Variants

Retailys UI Design Framework provides 5 sidebar navigation variants. Each is a self-contained component with built-in mobile responsiveness.

Simple

Width: 296px fixed

Logo, search input, collapsible nav items, feature card slot, and account card. This is the most full-featured sidebar variant.

Key Props

activeUrlitemsfooterItemsshowAccountCardfeatureCardhideBorder

Slim

Width: 68px collapsed, 268px on hover

Icon-only main rail with hover-expand secondary panel, spring animation, and avatar dropdown. Best for apps that need maximum content space.

Key Props

activeUrlitemsfooterItemshideBorderhideRightBorder

Dual-Tier

Width: 296px + 256px secondary panel on hover

Full main sidebar plus a hover secondary panel for nested items, search, and feature card. Ideal for apps with deep navigation hierarchies.

Key Props

activeUrlitemsfooterItemsfeatureCardhideBorder

Current

Sections + Subheadings

Width: 292px with rounded borders

Grouped sections with uppercase subheadings and a clean flat structure with account card.

Key Props

activeUrlitems (Array of { label, items })

Section Dividers

Width: 292px with rounded borders

Sections separated by horizontal dividers, search input, and collapsible items. Good for organizing nav into distinct functional groups.

Key Props

activeUrlitems (NavItemType | NavItemDividerType)[]

SidebarSimple Props

Props for the most full-featured sidebar variant.

Prop	Type	Default	Description
`activeUrl`	`string`	-	URL of the currently active item
`items`*	`NavItemType[]`	-	Main navigation items
`footerItems`	`NavItemType[]`	-	Footer section items
`showAccountCard`	`boolean`	`true`	Show account card at bottom
`featureCard`	`ReactNode`	-	Optional promotional card
`hideBorder`	`boolean`	-	Hide the right border

NavItemType

Shape of each navigation item passed to sidebar variants.

Prop	Type	Default	Description
`label`*	`string`	-	Navigation item label
`href`	`string`	-	URL destination
`icon`	`FC<{ className?: string }>`	-	Icon component
`badge`	`ReactNode`	-	Badge element (e.g., count)
`items`	`NavItemType[]`	-	Nested sub-items (for collapsible)
`divider`	`boolean`	-	Render as divider (SectionDividers variant)

Header Navigation

An alternative to sidebar navigation -- a horizontal header with primary and secondary nav rows.

HeaderNavigation

Primary header row (h-16, md: h-18) with logo, navigation items, settings, notifications, and avatar dropdown. A secondary header row auto-appears when the active item has sub-items. On mobile, the navigation collapses into a drawer overlay.

Primary Row

Logo + nav items + settings + notifications + avatar

Secondary Row

Auto-appears when active item has sub-items

Mobile

Collapses to drawer overlay

HeaderNavigation Props

Prop	Type	Default	Description
`activeUrl`	`string`	-	Currently active URL
`items`*	`NavItem[]`	-	Primary navigation items
`subItems`	`NavItem[]`	-	Secondary nav items (overrides auto-detection)
`trailingContent`	`ReactNode`	-	Content on the right side
`showAvatarDropdown`	`boolean`	`true`	Show avatar dropdown menu
`hideBorder`	`boolean`	-	Hide borders

Mobile Navigation

All navigation variants include built-in mobile responsiveness via MobileNavigationHeader.

MobileNavigationHeader

Every sidebar variant automatically renders a mobile header on screens below the lg breakpoint (1024px). The mobile header provides a consistent experience across all navigation styles.

h-16 header bar with logo, theme toggle, and hamburger menu button

Modal overlay renders the full sidebar content in a slide-in panel

Animated transitions with smooth slide-in and slide-out

Auto-dismiss on backdrop click or navigation

Theme System

The design system supports light and dark themes via CSS custom properties and next-themes.

Theme Toggle Variants

Button and switch styles at all available sizes.

switch

with label

Implementation

How the theme system is wired up.

ThemeProvider from next-themes

Uses the class strategy with attribute="class".

CSS class switching

.light-mode and .dark-mode classes on the root element toggle the theme.

CSS custom properties

Variables defined in theme.css automatically remap all semantic tokens between light and dark palettes.

System preference detection

enableSystem allows automatic theme selection based on the user's OS preference.

ThemeToggle Props

Prop	Type	Default	Description
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Toggle button size
`showLabel`	`boolean`	`false`	Show 'Light'/'Dark' label

Page Layout Pattern

The standard page layout used across all pages in this design manual.

Standard Layout Structure

Sidebar

292px

Sticky Header (h-16)

Main Content (max-w-7xl)

px-4 py-8 md:px-8 md:py-12

Key Characteristics

Sidebar + content layout using flex min-h-dvh lg:flex-row

Sticky header with sticky top-0 z-40 and backdrop blur

Content area constrained to max-w-7xl with responsive padding

Hidden on mobile — sidebar is replaced by MobileNavigationHeader below lg

Responsive Patterns

Tailwind CSS breakpoints used throughout the design system for responsive layout transitions.

Breakpoints

The standard Tailwind breakpoint scale and how each is used in the layout system.

sm

640px

Mobile landscape

md

768px

Tablet

lg

1024px

Desktop (sidebar appears)

xl

1280px

Large desktop

2xl

1536px

Ultra-wide

Layout Behavior by Breakpoint

Breakpoint	Navigation	Content
`< lg`	MobileNavigationHeader + drawer overlay	Full width, px-4 py-8
`lg`	Sidebar visible, sticky header appears	Flex-1 beside sidebar, max-w-7xl
`xl+`	Same as lg, wider content area	Increased horizontal padding, px-8 py-12