Spacing & UX Standards

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.

​

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

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

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

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

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

<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

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

​

Table of Contents

​

Core Patterns

• Page Container Pattern
• Sidebar Adaptive Layout
• Container Padding Standards

​

Dialog & Sheet Sizes

• Dialog Size Tiers
• Sheet Size Tiers
• Dialog/Sheet Decision Guide

​

Spacing Guidelines

• Vertical Spacing
• Card Padding
• Mobile-First Considerations
• Grid Layouts
• Form Spacing
• Table Spacing

​

Component Patterns

• Section Headers
• Page Header Pattern
• Stats Bar Pattern
• Content Grid Pattern

​

Dialog & Sheet Sizing

• Dialog Size Tiers
• Sheet Size Tiers
• Dialog Sizing Rules

​

Migration & Reference

• Migration Checklist
• Review History
• Related Documents

​

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

​

Standard Sheet Sizes

​

Dialog Sizing Rules

1. ALWAYS include sm: responsive prefix
2. NEVER use arbitrary pixel values ([425px], [500px], etc.)
3. NEVER add overflow-y-auto to DialogContent (base handles it)
4. 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

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

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

​

Overview Page Wrapper Pattern

​

When to Use

• 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

​

Sidebar Adaptive Layout

​

Critical Requirement: Content Expansion

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

// ✅ 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

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

​

Container Padding Standards

​

Standard Patterns

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

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

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

​

Anti-Patterns to Avoid

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

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

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

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

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

<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

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

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

​

Dialog Size Tiers

​

Sheet Size Tiers

​

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

​

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

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

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

​

Form Spacing

​

Standard Patterns

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

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

​

Table Spacing

​

Standard Patterns

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

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

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

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

​

Section Headers

​

Standard Patterns

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

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

​

Page Header Pattern

​

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

• 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

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

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

​

Inconsistent Spacing Between Breakpoints

// ❌ 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

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

​

Content Overlapping with Sidebar

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

​

Grid Items Too Close Together

// ❌ 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

// ❌ 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

// ❌ 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 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)

1. Content expansion when sidebar collapses
2. Container padding consistency
3. Responsive spacing patterns
4. Mobile-first design
5. Dead space elimination

​

Related Documents

• 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