Spacing & UX Standards - Encore Health OS

Version: 1.1.0
Last Updated: 2026-04-08
Status: Active

UI/UX Guide: For full UI/UX standards including design system, page templates, navigation, and accessibility, see UI_UX_STANDARDS.md. Scope: This file is spacing/layout specific; keep broad UI policy in UI_UX_STANDARDS.md to avoid duplication.

This document consolidates spacing and UX standards from previous review documents to provide a single source of truth for spacing patterns, responsive design, and UX consistency across the Encore Health OS platform.

Quick Reference

Standard Spacing Scale

// Mobile → Tablet → Desktop
xs:  8px  (0.5rem)  - Tight spacing (icons, badges)
sm:  12px (0.75rem) - Compact spacing (form fields)
md:  16px (1rem)    - Standard spacing (cards, sections)
lg:  24px (1.5rem)  - Large spacing (sections, groups)
xl:  32px (2rem)    - Extra large (major sections)
2xl: 48px (3rem)    - Page-level spacing

Common Patterns

Page Container:

<PageContainer spacing="md">{children}</PageContainer>

Vertical Spacing:

<div className="space-y-4 md:space-y-6">{items}</div>

Grid Spacing:

<div className="grid gap-3 md:gap-4 lg:gap-6 md:grid-cols-2">{items}</div>

Form Spacing:

<form className="space-y-4 md:space-y-6">{fields}</form>

Card Padding:

<Card className="p-4 md:p-6">{content}</Card>

Helper Components

PageContainer - Consistent responsive page-level padding
ResponsiveFormLayout - Responsive column layouts for forms
MobileTableWrapper - Horizontal scroll wrapper for wide tables

Best Practices

✅ Always use responsive spacing - space-y-4 md:space-y-6
✅ Use PageContainer - Don’t manually add container padding
✅ Consistent grid gaps - gap-3 md:gap-4 lg:gap-6
✅ Mobile-first - Start with mobile spacing, scale up
❌ Avoid fixed padding on all screen sizes
❌ Avoid double padding (container + explicit)
❌ Avoid inconsistent spacing patterns

For detailed patterns and examples, see sections below.

Dialog Size Tiers

Full Reference: See .cursor/rules/dialog-size-standards.md for complete standards and decision guide.
Audit: See docs/development/UI_CONSISTENCY_REVIEW.md for the full UI consistency audit.

Standard Dialog Sizes

Tier	Class	Width	Use Case
Small	`sm:max-w-md`	448px	Confirmations, simple forms (1-3 fields), quick actions, export options
Medium	`sm:max-w-lg`	512px	Standard forms (4-8 fields), settings panels, single-section content
Large	`sm:max-w-2xl`	672px	Complex forms, multi-section dialogs, forms with tables, email compose
X-Large	`sm:max-w-3xl`	768px	Large tables, comparison views, wizards, version history
Full	`sm:max-w-4xl`	896px	Document previews, code editors, full-width content, bulk operations

Standard Sheet Sizes

Tier	Class	Width	Use Case
Default	(no override)	75% / sm:384px	Quick panels, navigation, simple content
Medium	`sm:max-w-md`	448px	Chat panels, variable editors, AI assistant
Large	`sm:max-w-lg`	512px	Form panels, settings, approval workflows
X-Large	`sm:max-w-xl`	576px	Complex editors, test scenario editors
Wide	`sm:max-w-2xl`	672px	Wide previews, wizard previews

Dialog Sizing Rules

ALWAYS include sm: responsive prefix
NEVER use arbitrary pixel values ([425px], [500px], etc.)
NEVER add overflow-y-auto to DialogContent (base handles it)
NEVER add max-h-* to DialogContent (base provides sm:max-h-[85vh])

// ✅ CORRECT
<DialogContent className="sm:max-w-lg">

// ❌ WRONG
<DialogContent className="max-w-lg">                     // missing sm: prefix
<DialogContent className="sm:max-w-[500px]">              // arbitrary pixels
<DialogContent className="sm:max-w-lg max-h-[90vh] overflow-y-auto"> // redundant

Page Container Pattern

Standard Implementation

import { PageContainer } from '@/shared/components/PageContainer';

// Standard page
<PageContainer spacing="md">
  {/* Content */}
</PageContainer>

// Compact page
<PageContainer spacing="sm">
  {/* Content */}
</PageContainer>

// Spacious page
<PageContainer spacing="lg">
  {/* Content */}
</PageContainer>

Responsive Padding

Recommended Pattern:

Mobile: 16px (py-4 px-4)
Tablet: 24px (md:py-6 md:px-6)
Desktop: 32px (lg:py-8 lg:px-8)

Avoid:

❌ Fixed padding on all screen sizes
❌ Double padding (container + explicit padding)
❌ Container default padding (32px) on mobile

Overview Page Wrapper Pattern

When to Use

Use OverviewPageWrapper for:

Module landing pages (e.g., /hr, /rh, /fa)
Any page that needs pull-to-refresh with query invalidation
Pages following the standard overview structure

Standard Implementation

import { OverviewPageWrapper } from '@/shared/components';

<OverviewPageWrapper 
  refreshQueryKeys={['hr']} 
  spacing="md"
>
  {/* Page content */}
</OverviewPageWrapper>

Props Reference

Prop	Type	Default	Description
`refreshQueryKeys`	`string[]`	Required	Query keys to invalidate on refresh
`spacing`	`'sm' \| 'md' \| 'lg'`	`'md'`	Vertical spacing between sections
`maxWidth`	`'sm' \| ... \| 'full'`	`'7xl'`	Maximum content width
`onRefresh`	`() => Promise<void>`	-	Additional refresh handler
`disablePullToRefresh`	`boolean`	`false`	Disable PTR (rare use)

Critical Requirement: Content Expansion

Problem: Content must expand when sidebar collapses to utilize available space. Sidebar Dimensions:

Expanded: 16rem (256px)
Collapsed: 3rem (48px)
Available space when collapsed: +208px

Solution Pattern:

// ✅ CORRECT: Use flex-1 and responsive container
<div className="flex-1">
  <PageContainer className="w-full max-w-none">
    {/* Content adapts to available space */}
  </PageContainer>
</div>

// ❌ WRONG: Fixed max-width doesn't adapt
<div className="container mx-auto max-w-7xl">
  {/* Content stays same width regardless of sidebar */}
</div>

Implementation Guidelines

Use flex-1 on content container to fill available space
Remove fixed max-width or use responsive max-width
Use w-full to ensure content uses full available width
Test sidebar collapse to verify content expansion

Container Padding Standards

Standard Patterns

Pattern 1: Responsive Padding (Recommended)

<div className="p-4 md:p-6 lg:p-8">
  {/* Content */}
</div>

Pattern 2: Horizontal + Vertical Separate

<div className="py-6 px-4 md:px-6 lg:px-8">
  {/* Content */}
</div>

Pattern 3: PageContainer Component (Preferred)

<PageContainer spacing="md">
  {/* Content */}
</PageContainer>

Anti-Patterns to Avoid

❌ Double Padding:

// WRONG: Container already has 2rem padding
<div className="container mx-auto p-6">

❌ Fixed Padding on Mobile:

// WRONG: Too large for mobile
<div className="p-8">

❌ Inconsistent Patterns:

// WRONG: Mix of patterns in same codebase
<div className="p-4">  // Some places
<div className="p-6">  // Other places
<div className="container mx-auto">  // Yet others

Vertical Spacing

Standard Patterns

Between Sections:

<div className="space-y-6">
  <Section1 />
  <Section2 />
  <Section3 />
</div>

Between Cards:

<div className="grid gap-4 md:gap-6">
  <Card />
  <Card />
</div>

Responsive Spacing:

<div className="space-y-4 md:space-y-6 lg:space-y-8">
  {/* Content */}
</div>

Guidelines

Use space-y-* for vertical spacing between children
Use gap-* for grid/flex layouts
Scale spacing responsively: smaller on mobile, larger on desktop
Maintain consistent spacing scale (4, 6, 8, not 4, 5, 7)

Card Padding

Standard Patterns

Responsive Card Padding:

<Card className="p-4 md:p-6">
  {/* Card content */}
</Card>

Guidelines:

Mobile: p-4 (16px) - Prevents cramped cards
Tablet+: p-6 (24px) - Comfortable spacing
Avoid p-6 on mobile (too large)

Dialog Size Tiers

Use only these standard tiers for DialogContent. Always include the sm: prefix.

Tier	Class	Width	Use case
Small	`sm:max-w-md`	448px	Confirmations, simple forms (1–3 fields), quick actions, export options
Medium	`sm:max-w-lg`	512px	Standard forms (4–8 fields), settings panels, single-section content
Large	`sm:max-w-2xl`	672px	Complex forms, multi-section dialogs, forms with tables, email compose
X-Large	`sm:max-w-3xl`	768px	Large tables, comparison views, wizards, version history
Full	`sm:max-w-4xl`	896px	Document previews, code editors, full-width content, bulk operations

Do not use arbitrary pixel values (e.g. max-w-[425px]). The base dialog already provides sm:max-h-[85vh] and overflow; do not add max-h-* or overflow-y-auto on DialogContent.

Sheet Size Tiers

Use only these standard tiers for SheetContent. Always include the sm: prefix.

Tier	Class	Width	Use case
Default	(no override)	75% / sm:384px	Quick panels, navigation, simple content
Medium	`sm:max-w-md`	448px	Chat panels, variable editors, AI assistant
Large	`sm:max-w-lg`	512px	Form panels, settings, approval workflows
X-Large	`sm:max-w-xl`	576px	Complex editors, test scenario editors
Wide	`sm:max-w-2xl`	672px	Wide previews, wizard previews

Dialog/Sheet Decision Guide

Confirmation or 1–5 fields? → Dialog Small (sm:max-w-md) or Sheet Default/Medium
Standard form (4–8 fields)? → Dialog Medium (sm:max-w-lg) or Sheet Large
Multiple sections or tabs? → Dialog Large (sm:max-w-2xl)
Table or comparison view? → Dialog X-Large (sm:max-w-3xl)
Document preview or full editor? → Dialog Full (sm:max-w-4xl) or Sheet Wide

See also: .cursor/rules/dialog-size-standards.md for full rules and examples; docs/development/index.md for current migration and review status references.

Mobile-First Considerations

Touch Targets

Minimum: 44x44px (per constitution.md §6.7)
Recommended: 48x48px for primary actions
Spacing between targets: 8px minimum

Safe Area Insets

// Fixed navigation with safe area
<div className="fixed bottom-0 pb-safe">
  {/* Navigation */}
</div>

Responsive Breakpoints

// Standard breakpoints
sm:  640px  // Mobile landscape
md:  768px  // Tablet
lg:  1024px // Desktop
xl:  1280px // Large desktop
2xl: 1536px // Extra large

Grid Layouts

Responsive Grid Patterns

Standard Grid:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 md:gap-6">
  <Card />
  <Card />
  <Card />
</div>

Guidelines:

Start with single column on mobile
Add columns at tablet breakpoint (md:)
Use consistent gap spacing (4, 6, 8)

Form Spacing

Standard Patterns

Form Field Spacing:

<div className="space-y-4">
  <FormField />
  <FormField />
  <FormField />
</div>

Form Section Spacing:

<div className="space-y-6">
  <FormSection />
  <FormSection />
</div>

Table Spacing

Standard Patterns

Table Padding:

<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Column</TableHead>  {/* h-10 md:h-12, px-3 md:px-4 */}
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Data</TableCell>  {/* p-3 md:p-4 */}
    </TableRow>
  </TableBody>
</Table>

For Wide Tables on Mobile:

import { MobileTableWrapper } from '@/shared/components';

<MobileTableWrapper>
  <Table>
    {/* Wide table content */}
  </Table>
</MobileTableWrapper>

Table Spacing Guidelines:

Mobile: 12px (p-3)
Desktop: 16px (md:p-4)
Header Height: Mobile 40px (h-10), Desktop 48px (md:h-12)

Section Headers

Standard Patterns

Standard Section Header:

<h2 className="text-xl font-semibold mt-6 mb-3 md:mt-8 md:mb-4">
  Section Title
</h2>

With Description:

<div className="mb-4 md:mb-6">
  <h2 className="text-xl font-semibold">Section Title</h2>
  <p className="text-muted-foreground">Section description</p>
</div>

Standard Implementation

<div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-3 md:gap-4">
  <div>
    <h1 className="text-2xl md:text-3xl font-bold">Page Title</h1>
    <p className="text-muted-foreground">Page description</p>
  </div>
  <Button>Action</Button>
</div>

Stats Bar Pattern

Standard Implementation

<div className="grid gap-3 md:gap-4 lg:gap-6 grid-cols-1 sm:grid-cols-2 lg:grid-cols-4">
  {stats.map((stat) => (
    <Card key={stat.id}>
      {/* Stat content */}
    </Card>
  ))}
</div>

Content Grid Pattern

Standard Implementation

<div className="grid gap-3 md:gap-4 md:grid-cols-2 lg:grid-cols-3">
  {items.map((item) => (
    <Card key={item.id}>
      {/* Item content */}
    </Card>
  ))}
</div>

Migration Checklist

When updating a page to follow spacing standards:

Replace container mx-auto p-6 with PageContainer
Replace space-y-6 with space-y-4 md:space-y-6
Replace gap-4/gap-6 with gap-3 md:gap-4 lg:gap-6
Update manual margins to use spacing system
Test on mobile (320px), tablet (768px), desktop (1024px+)
Verify no horizontal scrolling
Verify content doesn’t touch edges

Troubleshooting Common Issues

Content Touching Screen Edges on Mobile

Problem: Content appears to touch the left/right edges on mobile devices. Solution:

// ❌ WRONG: Missing container padding
<div className="space-y-4">{content}</div>

// ✅ CORRECT: Use PageContainer
<PageContainer spacing="md">{content}</PageContainer>

Inconsistent Spacing Between Breakpoints

Problem: Spacing jumps dramatically between mobile and desktop. Solution:

// ❌ WRONG: Fixed spacing
<div className="space-y-6">{items}</div>

// ✅ CORRECT: Responsive spacing
<div className="space-y-4 md:space-y-6">{items}</div>

Horizontal Scrolling on Mobile

Problem: Page scrolls horizontally on mobile devices. Solution:

Check for fixed-width elements: Remove w-{fixed} classes
Use responsive grid: grid-cols-1 md:grid-cols-2
Check container: Ensure PageContainer is used, not manual padding
Verify safe areas: Check for elements extending beyond viewport

Content Overlapping with Sidebar

Problem: Content overlaps when sidebar is visible. Solution:

// ✅ CORRECT: Use sidebar-adaptive layout
<div className="ml-0 md:ml-64">
  <PageContainer spacing="md">{content}</PageContainer>
</div>

Grid Items Too Close Together

Problem: Grid items have insufficient spacing. Solution:

// ❌ WRONG: No gap
<div className="grid grid-cols-2">{items}</div>

// ✅ CORRECT: Responsive gap
<div className="grid gap-3 md:gap-4 lg:gap-6 grid-cols-1 md:grid-cols-2">{items}</div>

Form Fields Too Tight

Problem: Form fields appear cramped. Solution:

// ❌ WRONG: Tight spacing
<form className="space-y-2">{fields}</form>

// ✅ CORRECT: Standard form spacing
<form className="space-y-4 md:space-y-6">{fields}</form>

Cards Have Inconsistent Padding

Problem: Some cards have different padding than others. Solution:

// ❌ WRONG: Inconsistent padding
<Card className="p-4">Content</Card>
<Card className="p-6">Content</Card>

// ✅ CORRECT: Standard card padding
<Card className="p-4 md:p-6">Content</Card>

Review History

This document consolidates content from:

This document consolidates content from SPACING_AND_SIDEBAR_ADAPTIVE_REVIEW.md (archived 2025-12-08)
This document consolidates content from SPACING_AND_UX_REVIEW.md (archived 2025-01-27)
SPACING_QUICK_REFERENCE.md (2025-01-27) - Quick reference guide (consolidated)

Key Issues Addressed:

Content expansion when sidebar collapses
Container padding consistency
Responsive spacing patterns
Mobile-first design
Dead space elimination

Constitution: constitution.md §6.7 - UI/UX guardrails
Navigation Standards: docs/architecture/NAVIGATION_STANDARD.md - Navigation patterns
UI/UX Standards: docs/development/UI_UX_STANDARDS.md - Full UI/UX guide
Dialog/Sheet size rules: .cursor/rules/dialog-size-standards.md - Required size tiers and anti-patterns
UI consistency review: docs/development/UI_CONSISTENCY_REVIEW.md - Migration status and remaining work

Architecture

Development

Database

Testing

Migration

Operations

Governance & Security

Platform Internals

Documentation Index

​Quick Reference

​Standard Spacing Scale

​Common Patterns

​Helper Components

​Best Practices

​Table of Contents

​Core Patterns

​Dialog & Sheet Sizes

​Spacing Guidelines

​Component Patterns

​Dialog & Sheet Sizing

​Migration & Reference

​Dialog Size Tiers

​Standard Dialog Sizes

​Standard Sheet Sizes

​Dialog Sizing Rules

​Page Container Pattern

​Standard Implementation

​Responsive Padding

​Overview Page Wrapper Pattern

​When to Use

​Standard Implementation

​Props Reference

​Sidebar Adaptive Layout

​Critical Requirement: Content Expansion

​Implementation Guidelines

​Container Padding Standards

​Standard Patterns

​Anti-Patterns to Avoid

​Vertical Spacing

​Standard Patterns

​Guidelines

​Card Padding

​Standard Patterns

​Dialog Size Tiers

​Sheet Size Tiers

​Dialog/Sheet Decision Guide

​Mobile-First Considerations

​Touch Targets

​Safe Area Insets

​Responsive Breakpoints

​Grid Layouts

​Responsive Grid Patterns

​Form Spacing

​Standard Patterns

​Table Spacing

​Standard Patterns

​Section Headers

​Standard Patterns

​Page Header Pattern

​Standard Implementation

​Stats Bar Pattern

​Standard Implementation

​Content Grid Pattern

​Standard Implementation

​Migration Checklist

​Troubleshooting Common Issues

​Content Touching Screen Edges on Mobile

​Inconsistent Spacing Between Breakpoints

​Horizontal Scrolling on Mobile

​Content Overlapping with Sidebar

​Grid Items Too Close Together

​Form Fields Too Tight

​Cards Have Inconsistent Padding

​Review History

​Related Documents

Quick Reference

Standard Spacing Scale

Common Patterns

Helper Components

Best Practices

Table of Contents

Core Patterns

Dialog & Sheet Sizes

Spacing Guidelines

Component Patterns

Dialog & Sheet Sizing

Migration & Reference

Dialog Size Tiers

Standard Dialog Sizes

Standard Sheet Sizes

Dialog Sizing Rules

Page Container Pattern

Standard Implementation

Responsive Padding

Overview Page Wrapper Pattern

When to Use

Standard Implementation

Props Reference

Sidebar Adaptive Layout

Critical Requirement: Content Expansion

Implementation Guidelines

Container Padding Standards

Standard Patterns

Anti-Patterns to Avoid

Vertical Spacing

Standard Patterns

Guidelines

Card Padding

Standard Patterns

Dialog Size Tiers

Sheet Size Tiers

Dialog/Sheet Decision Guide

Mobile-First Considerations

Touch Targets

Safe Area Insets

Responsive Breakpoints

Grid Layouts

Responsive Grid Patterns

Form Spacing

Standard Patterns

Table Spacing

Standard Patterns

Section Headers

Standard Patterns

Page Header Pattern

Standard Implementation

Stats Bar Pattern

Standard Implementation

Content Grid Pattern

Standard Implementation

Migration Checklist

Troubleshooting Common Issues

Content Touching Screen Edges on Mobile

Inconsistent Spacing Between Breakpoints

Horizontal Scrolling on Mobile

Content Overlapping with Sidebar

Grid Items Too Close Together

Form Fields Too Tight

Cards Have Inconsistent Padding

Review History

Related Documents