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

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

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

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

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

---

🔴 Critical Issues to Fix (Session 2026-08-16)

1. FormPageLayout

File: frontend/src/shared/ui/layouts/FormPageLayout.vue
Current: grid-template-columns: minmax(0, 1fr) minmax(18rem, 26rem);
Fix: grid-template-columns: minmax(0, 1fr) var(--ks-preview-width);
Breakpoint: Change from 950px to 1100px
Pages Affected: MarketDataIngestion, EditFormPage, etc.

2. ReviewWorkbenchLayout

File: frontend/src/shared/ui/layouts/ReviewWorkbenchLayout.vue
Current: grid-template-columns: minmax(18rem, 28rem) minmax(24rem, 1fr) minmax(18rem, 24rem);
Fix: grid-template-columns: var(--ks-sidebar-width) minmax(0, 1fr) var(--ks-aside-width);
Breakpoint: Change from 1200px to 1100px
Pages Affected: ApprovalQueue (master-detail), review screens

3. OperationsConsoleLayout

File: frontend/src/shared/ui/layouts/OperationsConsoleLayout.vue
Current: grid-template-columns: minmax(18rem, 28rem) minmax(0, 1fr);
Fix: grid-template-columns: var(--ks-detail-width) minmax(0, 1fr);
Breakpoint: Standardize to 1100px
Pages Affected: Operations console

---

📚 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.0	2026-08-16	Initial standard; fixes 3 layouts; establishes CSS variable system