Layout & Navigation

Layout and navigation are the structural decisions that shape how users perceive and move through the product. Where Component Patterns documents the dashboard shell implementation, this page documents the reasoning behind the layout decisions.

Design-First Philosophy: Desktop-First Design, Mobile-First CSS

These sound contradictory but they address independent dimensions:

• Design priority is desktop. B2B SaaS receives 65-74% desktop traffic (71% during business hours). The desktop experience is where users perform primary work -- dashboards, data tables, complex research workflows. Design this first.
• CSS authoring direction is mobile-first. Tailwind CSS uses min-width breakpoints: unprefixed classes apply to all sizes, prefixed classes (md:, lg:) add complexity upward. This produces cleaner, more maintainable code.

In practice: think about the desktop layout first, then simplify it systematically for smaller screens. Write the CSS starting from the simplified mobile layout and building up.

Four-Breakpoint System

Breakpoint	Prefix	Width	What changes
Base	(none)	0-639px	Single column, off-canvas nav drawer, stacked widgets, card view for tables
sm	sm:	640px+	Minor layout tweaks: two-column stat grids, paired form fields
md	md:	768px+	First major transition: collapsed sidebar visible (64px, icons only), two-column content
lg	lg:	1024px+	Second major transition: sidebar expands (240px with labels), 2-3 column dashboard grids
xl	xl:	1280px+	Content reaches max-width (1200-1400px), refinements only

The 2xl breakpoint (1536px) is intentionally omitted. It can be added later if analytics show significant ultra-wide usage.

Three-State Sidebar

The sidebar is the primary navigation mechanism. Its responsive behavior is the most visible layout decision in the product.

State	Viewport	Width	Behavior
Expanded	lg+ (1024px+)	240px	Icon + text labels, section headers, workspace switcher. User can manually collapse (persists via cookie).
Collapsed	md-lg (768-1023px)	64px	Icons only, tooltips on hover. Navigation without consuming content space.
Off-canvas	Below md (< 768px)	Hidden	Hamburger icon triggers a drawer overlay with backdrop. Closes on navigation or backdrop tap.

Implemented via shadcn/ui's Sidebar component with collapsible="icon". The useSidebar hook provides programmatic control. Toggle shortcut: Cmd+B / Ctrl+B.

Content Area Math

Viewport	Sidebar	Content width	Assessment
1280px (xl)	240px expanded	1040px	Excellent -- full dashboard
1024px (lg)	240px expanded	784px	Good -- two-column dashboard
768px (md)	64px collapsed	704px	Good -- two-column content
375px (base)	0px hidden	375px	Minimum -- single column

Sidebar Architecture: Five Zones

The sidebar is organized into five zones from top to bottom:

+-------------------------+
|  Workspace Switcher     |  Zone 1: Tenant context (name + avatar)
+-------------------------+
|  Search / Cmd+K         |  Zone 2: Quick access (command palette trigger)
+-------------------------+
|  > Dashboard            |
|  > [Core Feature]       |  Zone 3: Primary navigation (accordion sections)
|  > [Feature Group]      |
+-------------------------+
|  > Settings             |  Zone 4: Configuration (role-filtered)
|  > Admin (role-gated)   |
+-------------------------+
|  User Profile           |  Zone 5: Account (avatar + name + sign out)
+-------------------------+

Design Principles

• Background slightly dimmer than main content -- navigation recedes, content takes focus.
• Active item -- subtle background highlight + primary color text + filled icon variant.
• Hover -- light background tint, 150ms transition.
• Sidebar toggle -- Cmd+B / Ctrl+B, persists via cookies.

Accordion Grouping for Scalability

Navigation grows with the product. Accordion groups keep it manageable:

• At launch (8-12 items): flat list with one or two collapsible groups.
• At growth (15-25 items): 5-7 top-level groups, each containing 3-8 items. Active item's parent group auto-expands on page load.
• Collapsed sidebar shows only top-level group icons -- clicking temporarily expands a floating panel with sub-items.

Role-Based Filtering

Navigation items are conditionally rendered based on the user's role in the current tenant. This is a security requirement -- never show nav items that produce permission errors when clicked.

Role	Visible sections
Admin/Owner	All sections including Team Management, Billing, API Keys
Member	All feature sections, personal Settings, no Admin sections
Viewer	Read-only feature sections, personal Settings only
Guest	Limited feature access as defined by invitation scope

Command Palette (Cmd+K)

A power-user navigation accelerator using shadcn/ui's Command component (built on cmdk). Three functions:

1. Speed -- type "billing" faster than clicking through Settings > Billing.
2. Feature discovery -- new users search for capabilities and find them (or learn they don't exist).
3. Action execution -- trigger actions from anywhere: "Create new project," "Switch to dark mode."

Phased Content

Category	Items	Phase
Navigation	All sidebar routes	MVP
Quick actions	Create, invite, export	MVP
Settings	Theme, notifications, profile	MVP
Recent items	Last 10 visited pages	Post-launch
Entity search	Projects, users, documents (API, debounced)	Post-launch
Context actions	Actions available on current page	Growth

Visual Design

Centered modal overlay with backdrop blur, search input at top, grouped results with section headers. Width 640px on desktop, full-width on mobile. Open/close animation: scale 95% to 100% + fade (150ms).

Workspace Switcher

At the top of the sidebar (Zone 1). Shows current workspace name and avatar. Dropdown to switch between workspaces -- personal, family, and company accounts as defined by the three-tier tenant model.

The switcher must:

• Show all workspaces the user belongs to
• Indicate the current workspace clearly
• Switch context immediately (navigation items, data, and permissions update)
• Be accessible from the command palette ("Switch to [workspace name]")

Layout Patterns by View Type

These patterns guide how each type of screen is structured responsively:

View type	Desktop (lg+)	Tablet (md)	Mobile
Dashboard	3-4 column stat grid, 2-column charts, full-width table	2-column stats, charts stack	Single column throughout
List views	Full data table, inline actions, filter bar	Reduced columns, collapsed filters	Card layout (each row becomes a card)
Detail views	Two-column: main (60-70%) + metadata sidebar (30-40%)	Narrower metadata panel	Single column, metadata stacked below
Settings	Left nav sidebar (200px) + content (max-width 600-800px)	Nav collapses to top tabs	Category list > dedicated pages
Forms	Two-column for paired fields, max-width 600-800px	Same or slightly narrower	Single column, all fields stacked
Empty states	Centered, max-w-md	Same	Same -- only sizing scales

Keyboard Navigation and Accessibility

Non-negotiable requirements (European Accessibility Act effective June 2025, WCAG 2.2 Level AA):

• Skip link -- every page has "Skip to main content" as the first focusable element, visually hidden until keyboard focus.
• Focus order -- tab order follows visual flow. Never use tabindex values greater than 0.
• Modal focus trap -- when a modal/dialog/drawer opens, focus moves inside and cycles within it. Focus returns to the trigger on close.
• Route change focus -- navigating to a new page moves focus to the page heading or <main>.
• Focus-visible styling -- custom branded focus indicator using :focus-visible, showing the ring only for keyboard navigation.

Launch Keyboard Shortcuts

Shortcut	Action
Cmd+K / Ctrl+K	Open command palette
Cmd+B / Ctrl+B	Toggle sidebar
Escape	Close modal/dialog/command palette
Tab / Shift+Tab	Move focus forward/backward
Enter / Space	Activate focused element
Arrow keys	Navigate within menus, tabs, lists

Container Queries vs. Media Queries

• Media queries (Tailwind responsive prefixes) -- for page-level decisions: sidebar visibility, column counts, global spacing.
• Container queries (Tailwind @container + @md:, @lg:) -- for reusable components that appear in contexts of varying width: dashboard widgets, cards in narrow or wide columns.

Container queries are first-class in Tailwind v4 (no plugins). This is critical for dashboard widgets -- a stat card should show a compact layout in a narrow column and an expanded layout in a wide column, regardless of viewport size.

What Can Wait

• Customizable sidebar (pin, reorder, hide items) -- explicitly a $200K+ MRR feature. Deferred.
• Bottom tab bar for mobile web -- only if analytics show >30% mobile product usage after launch.
• Page navigation transitions -- instant navigation at MVP; animation added post-launch if desired.

Related Pages

• Component Patterns -- dashboard shell implementation, sidebar components
• Routing & Pages -- route structure, middleware, page patterns
• Interaction Patterns -- animation timing for sidebar and command palette