headquarter/openspec/changes/responsive-spacing-improvements/design.md

Responsive Spacing Improvements - Design

Architecture

Responsive Design System
├── CSS Custom Properties
│   ├── Spacing Scale (--space-1 to --space-10)
│   ├── Breakpoints (--bp-sm, --bp-md, --bp-lg, --bp-xl)
│   └── Fluid Typography (--font-size-*)
├── Layout Components
│   ├── Container (max-width + padding)
│   ├── Stack (vertical spacing)
│   ├── Row (horizontal spacing)
│   └── Grid (responsive columns)
├── Component Updates
│   ├── Tables (responsive wrapper)
│   ├── Dialogs (viewport-aware sizing)
│   ├── Cards (flexible grid)
│   └── Forms (full-width inputs)
└── Utility Classes
    ├── Display (hide/show at breakpoints)
    ├── Spacing (margin/padding helpers)
    └── Text (truncate, wrap, size)

Spacing Scale

Base Unit: 4px (0.25rem)

Token	Value	Usage
--space-1	0.25rem (4px)	Tight gaps, icon margins
--space-2	0.5rem (8px)	Small gaps, button padding
--space-3	0.75rem (12px)	Medium gaps
--space-4	1rem (16px)	Standard padding
--space-5	1.5rem (24px)	Section padding
--space-6	2rem (32px)	Large sections
--space-8	3rem (48px)	Page padding
--space-10	4rem (64px)	Hero sections

Breakpoint System

Mobile-First Approach

/* Base styles (mobile) */
.component { ... }

/* Small devices */
@media (min-width: 480px) { ... }

/* Medium devices */
@media (min-width: 768px) { ... }

/* Large devices */
@media (min-width: 1024px) { ... }

/* Extra large devices */
@media (min-width: 1280px) { ... }

Component Patterns

Container

.container {
  width: 100%;
  max-width: min(1200px, 100vw - 2rem);
  margin-inline: auto;
  padding-inline: var(--space-4);
}

Stack (Vertical Layout)

.stack {
  display: flex;
  flex-direction: column;
  gap: var(--space-4);
}

.stack-sm { gap: var(--space-2); }
.stack-md { gap: var(--space-4); }
.stack-lg { gap: var(--space-6); }

Row (Horizontal Layout)

.row {
  display: flex;
  flex-wrap: wrap;
  gap: var(--space-4);
  align-items: center;
}

Grid

.grid {
  display: grid;
  gap: var(--space-4);
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 300px), 1fr));
}

Responsive Tables

Mobile: Card Layout

@media (max-width: 767px) {
  .table-responsive {
    display: block;
  }
  .table-responsive thead {
    display: none;
  }
  .table-responsive tbody tr {
    display: block;
    margin-bottom: var(--space-4);
    border: 1px solid var(--border);
    border-radius: 8px;
    padding: var(--space-4);
  }
  .table-responsive td {
    display: flex;
    justify-content: space-between;
    padding: var(--space-2) 0;
    border-bottom: 1px solid var(--border-light);
  }
  .table-responsive td::before {
    content: attr(data-label);
    font-weight: 600;
  }
}

Dialog Sizing

.dialog {
  width: min(560px, 100vw - 2rem);
  max-height: min(800px, 100vh - 2rem);
  overflow-y: auto;
}

.dialog-lg {
  width: min(800px, 100vw - 2rem);
}

.dialog-fullscreen-mobile {
  width: 100vw;
  height: 100vh;
  max-height: 100vh;
  border-radius: 0;
}

@media (min-width: 768px) {
  .dialog-fullscreen-mobile {
    width: min(560px, 100vw - 2rem);
    height: auto;
    max-height: min(800px, 100vh - 2rem);
    border-radius: 12px;
  }
}

Touch Targets

.button,
.nav-link,
.icon-button {
  min-height: 44px;
  min-width: 44px;
}

/* Larger touch targets on mobile */
@media (max-width: 767px) {
  .button {
    padding: var(--space-3) var(--space-4);
  }
}

Text Handling

.truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.truncate-multiline {
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

.break-word {
  overflow-wrap: break-word;
  word-wrap: break-word;
  hyphens: auto;
}

Migration Strategy

Phase 1: CSS Custom Properties

• Add spacing scale to :root
• Add breakpoint custom properties
• Add fluid typography

Phase 2: Layout Utilities

• Create Container, Stack, Row, Grid utilities
• Update existing layouts to use utilities

Phase 3: Component Updates

• Update all pages with responsive patterns
• Fix overflow issues
• Add touch-friendly sizing

Phase 4: Testing

• Test on multiple viewport sizes
• Verify no horizontal overflow
• Check touch target sizes