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

```css
/* 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
```css
.container {
  width: 100%;
  max-width: min(1200px, 100vw - 2rem);
  margin-inline: auto;
  padding-inline: var(--space-4);
}
```

### Stack (Vertical Layout)
```css
.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)
```css
.row {
  display: flex;
  flex-wrap: wrap;
  gap: var(--space-4);
  align-items: center;
}
```

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

## Responsive Tables

### Mobile: Card Layout
```css
@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

```css
.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

```css
.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

```css
.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