KArtSell.Aegis/docs/FRONTEND-RESPONSIVE-DESIGN-STANDARD.md

# Frontend Responsive Design Standard v1.0

**Status:** ACTIVE  
**Authority:** AGENTS.md v16.0  
**Last Updated:** 2026-08-16

---

## 📌 Core Principle

**Responsive web design is MANDATORY for all layouts, not optional.**

All layouts must support mobile (768px), tablet (1100px), and desktop (1400px+) seamlessly.

**Reference:** AGENTS.md § "Frontend Layout & Responsive Design Standards"

---

## 🎯 Quick Rules

| Rule | ❌ DON'T | ✅ DO |
|------|---------|--------|
| Width | `minmax(18rem, 26rem)` | `var(--ks-preview-width)` |
| Breakpoint | 950px, 900px, 1000px, 1200px (mixed) | 1100px (tablet), 768px (mobile) |
| Flex Child | `flex: 1` only | `flex: 1; min-height: 0;` |
| Scroll | `height: calc(100vh - 220px)` | `flex: 1; min-height: 0; overflow-y: auto;` |
| Grid Align | `align-items: center` | `align-items: start` |
| Max Width | None (distorts at 2560px+) | `max-width: 1400px; margin: 0 auto;` |

---

## 📐 CSS Variable Standards

**Location:** `frontend/src/design-system/base.css`

**Standard widths (ALWAYS use these, NEVER hardcode):**
```css
:root {
  --ks-sidebar-width: 16rem;       /* Navigation sidebars */
  --ks-aside-width: 22rem;         /* Side panels (PageLayout) */
  --ks-preview-width: 24rem;       /* Preview/summary panels (FormPageLayout) */
  --ks-detail-width: 28rem;        /* Detail panels (ReviewWorkbenchLayout) */
  --ks-content-max: 1400px;        /* Max page width (prevent 2560px+ distortion) */
}
```

**Standard breakpoints (ALWAYS use these, NEVER create new breakpoints):**
```css
/* Tablet: 2-col → 1-col */
@media (max-width: 1100px) { 
  .layout { grid-template-columns: 1fr; }
}

/* Mobile: adjust spacing */
@media (max-width: 768px) { 
  .layout { padding: 0.75rem; }
  .layout h1 { font-size: 1.25rem; }
}
```

---

## 🔗 Layout Examples

### ✅ Correct: CSS Variable Based

```css
/* FormPageLayout (correct) */
.ks-form-layout {
  display: grid;
  grid-template-columns: minmax(0, 1fr) var(--ks-preview-width);
  gap: var(--ks-space-4);
  flex: 1;
  min-height: 0;
  height: 100%;
}

@media (max-width: 1100px) {
  .ks-form-layout { grid-template-columns: 1fr; }
}
```

### ❌ Wrong: Hardcoded Widths

```css
/* FormPageLayout (WRONG - current) */
.ks-form-layout {
  display: grid;
  grid-template-columns: minmax(0, 1fr) minmax(18rem, 26rem);
  /* Problems:
     - 1950px+: right column = 26rem (hardcoded), left = excessive
     - Not maintainable: width is hard to find/change
     - Not scalable: doesn't adapt to design changes
  */
}

@media (max-width: 950px) {
  /* Wrong: 950px is arbitrary, not shared with other layouts */
  .ks-form-layout { grid-template-columns: 1fr; }
}
```

---

## 🏗️ Height Propagation Chain (Non-Negotiable)

Every page MUST follow this chain. Each level must propagate height to the next.

```
1. PageLayout (.ks-page__content)
   └─ height: 100%; min-height: 0; display: flex; flex-direction: column;

2. QueryStateBoundary (.ks-query-boundary)
   └─ flex: 1; height: 100%; min-height: 0; display: flex; flex-direction: column;

3. Content Container (KsSplitter / .ks-stack / FormPageLayout / etc)
   ├─ flex: 1; min-height: 0; height: 100%;
   ├─ display: flex/grid;
   └─ overflow: hidden;

4. Internal Panes (.request-list, .detail-panel, .items, etc)
   └─ flex: 1; min-height: 0; overflow-y: auto; (enables internal scroll)
```

**Result:** Page fits single viewport. Only internal panes scroll.

---

## ✅ Verification Checklist

For EVERY layout change, verify:

- [ ] **Variables:** Uses `var(--ks-*-width)`, not hardcoded `18rem` / `26rem` / `28rem`
- [ ] **Breakpoints:** Uses standard 1100px (tablet) and 768px (mobile)
- [ ] **Flex children:** All have `flex: 1; min-height: 0;`
- [ ] **Scrollable panes:** Have `overflow-y: auto; min-height: 0;`
- [ ] **Max-width:** Wraps content in `max-width: 1400px; margin: 0 auto;` to prevent 2560px+ distortion
- [ ] **Tested:** 
  - [ ] 768px (mobile)
  - [ ] 1100px (tablet breakpoint)
  - [ ] 1512px (current test resolution)
  - [ ] 1920px (fullHD)
  - [ ] 2560px (4K)
- [ ] **Result:** No page-level scroll on first load; only internal panes scroll if content exceeds height
- [ ] **Grid align:** Uses `align-items: start` (not center/stretch)

---

## ✅ Standardization Complete (Session 2026-08-16)

### All 7 Layouts Fixed

| Layout | Status | Variables | Breakpoint | Pages |
|--------|--------|-----------|-----------|-------|
| FormPageLayout | ✅ FIXED | `var(--ks-preview-width)` | 1100px | MarketDataIngestion, EditFormPage |
| ReviewWorkbenchLayout | ✅ FIXED | `var(--ks-detail-width)` + `var(--ks-aside-width)` | 1100px | ApprovalQueue, review screens |
| OperationsConsoleLayout | ✅ FIXED | `var(--ks-detail-width)` | 1100px | Operations console |
| PageLayout | ✅ FIXED | footer overflow resolved | N/A | Global page shell |
| CrudWorkspaceLayout | ✅ COMPLIANT | `var(--ks-crud-aside)` | 1100px | CRUD operations |
| DashboardLayout | ✅ FIXED | 2fr 1fr (ratio OK) | 1100px → **900px** | Dashboard screens |
| AppShellLayout | ✅ FIXED | `var(--ks-sidebar-width)` | 1100px | App shell (global) |

---

## 📚 Related Documents

- **AGENTS.md v16.0:** Authoritative source for all engineering rules
  - § "Frontend Layout & Responsive Design Standards"
- **ADR-LAYOUT-HEIGHT-PROPAGATION:** Height propagation principles
- **CLAUDE.md:** Project context (architecture overview, navigation)

---

## 🎓 For AI Agents / LLMs

**When implementing any layout:**

1. **Check AGENTS.md first** (source of truth)
2. **Consult this document** for standard variables and breakpoints
3. **Verify against checklist** before committing
4. **Reference variables in CSS:** Always use `var(--ks-*-width)` for width constraints
5. **Uniform breakpoints:** Use ONLY 1100px (tablet) and 768px (mobile)
6. **Height chain:** Ensure flex: 1 / min-height: 0 propagates through all levels

**BANNED:** Hardcoded pixel/rem widths in grid-template-columns. Always use CSS variables.

---

## Version History

| Version | Date | Change |
|---------|------|--------|
| v1.1 | 2026-08-16 | **COMPLETE**: All 7 layouts standardized (CSS variables, unified 1100px breakpoint) |
| v1.0 | 2026-08-16 | Initial standard; fixes 3 layouts; establishes CSS variable system |