layout-patterns

Standard for complex layouts:

Layout Patterns

Grid Systems

12-Column Grid

Standard for complex layouts:

.container {
  display: grid;
  grid-template-columns: repeat(12, 1fr);
  gap: var(--space-4);
}

.col-6 {
  grid-column: span 6; /* Half width */
}

.col-4 {
  grid-column: span 4; /* Third width */
}

.col-3 {
  grid-column: span 3; /* Quarter width */
}

CSS Grid vs Flexbox

Use CSS Grid for:

• 2D layouts (rows AND columns)
• Complex, structured layouts
• Overlapping elements
• Precise placement

.grid-layout {
  display: grid;
  grid-template-columns: 250px 1fr 300px; /* sidebar, main, aside */
  grid-template-rows: auto 1fr auto; /* header, content, footer */
  gap: var(--space-4);
}

Use Flexbox for:

• 1D layouts (single axis)
• Dynamic content sizing
• Alignment within containers
• Navigation, toolbars

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

Container Widths

:root {
  --container-sm: 640px;
  --container-md: 768px;
  --container-lg: 1024px;
  --container-xl: 1280px;
  --container-2xl: 1536px;
}

.container {
  max-width: var(--container-xl);
  margin: 0 auto;
  padding: 0 var(--space-4);
}

Responsive Breakpoints

Mobile-first approach:

/* Mobile base styles (< 640px) */
.element {
  padding: var(--space-4);
  flex-direction: column;
}

/* Tablet (≥ 640px) */
@media (min-width: 640px) {
  .element {
    padding: var(--space-6);
  }
}

/* Desktop (≥ 1024px) */
@media (min-width: 1024px) {
  .element {
    padding: var(--space-8);
    flex-direction: row;
  }
}

/* Large desktop (≥ 1280px) */
@media (min-width: 1280px) {
  .element {
    padding: var(--space-12);
  }
}

Responsive Patterns

Stack on mobile, side-by-side on desktop:

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

@media (min-width: 768px) {
  .responsive-layout {
    flex-direction: row;
  }
}

Single column mobile, multi-column desktop:

.responsive-grid {
  display: grid;
  grid-template-columns: 1fr; /* mobile: 1 column */
  gap: var(--space-4);
}

@media (min-width: 768px) {
  .responsive-grid {
    grid-template-columns: repeat(2, 1fr); /* tablet: 2 columns */
  }
}

@media (min-width: 1024px) {
  .responsive-grid {
    grid-template-columns: repeat(3, 1fr); /* desktop: 3 columns */
  }
}

Layout Inspiration

Vercel Style

• Generous white space (--space-12 to --space-24 between sections)
• Large, clear typography
• Subtle gradients and blurs
• Minimal borders, maximum contrast
• Hero sections with strong CTAs

.vercel-hero {
  padding: var(--space-24) var(--space-4);
  text-align: center;
  background: linear-gradient(to bottom, var(--color-background), var(--color-muted));
}

Hex Style

• Data-dense but organized
• Strong visual hierarchy with cards
• Card-based layouts with clear groupings
• Effective use of color to categorize

.hex-card {
  background: var(--color-background);
  border: 1px solid var(--color-border);
  border-radius: 8px;
  padding: var(--space-6);
  box-shadow: var(--shadow-sm);
}

Baseten Style

• Clear documentation structure
• Code examples integrated smoothly
• Left sidebar navigation (250px width)
• Right sidebar table of contents (250px width)
• Main content centered (800px max-width)

.baseten-layout {
  display: grid;
  grid-template-columns: 250px 1fr 250px;
  gap: var(--space-8);
}

@media (max-width: 1024px) {
  .baseten-layout {
    grid-template-columns: 1fr; /* stack on mobile */
  }
}

Touch Targets

Minimum 44x44px for touch interfaces:

.touch-target {
  min-width: 44px;
  min-height: 44px;
  padding: var(--space-3);
  /* Ensure actual interactive area, not just visible area */
}

/* Increase spacing between touch targets on mobile */
@media (max-width: 640px) {
  .touch-toolbar {
    gap: var(--space-4); /* 16px between buttons */
  }
}

Common Layout Patterns

Dashboard Layout

.dashboard {
  display: grid;
  grid-template-areas:
    "header header header"
    "sidebar main aside"
    "footer footer footer";
  grid-template-columns: 250px 1fr 300px;
  grid-template-rows: auto 1fr auto;
  min-height: 100vh;
}

.dashboard-header { grid-area: header; }
.dashboard-sidebar { grid-area: sidebar; }
.dashboard-main { grid-area: main; }
.dashboard-aside { grid-area: aside; }
.dashboard-footer { grid-area: footer; }

Documentation Layout

.docs-layout {
  display: grid;
  grid-template-columns: 250px minmax(0, 800px) 250px;
  gap: var(--space-8);
  max-width: var(--container-2xl);
  margin: 0 auto;
  padding: var(--space-4);
}

.docs-nav { /* left sidebar */ }
.docs-content { /* main content */ }
.docs-toc { /* right sidebar table of contents */ }

Card Grid

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

/* Cards automatically wrap and maintain consistent width */

Best Practices

Do:

• ✅ Start mobile-first, enhance for larger screens
• ✅ Use CSS Grid for 2D layouts
• ✅ Use Flexbox for 1D layouts
• ✅ Test on multiple device sizes
• ✅ Ensure touch targets are ≥ 44x44px
• ✅ Use consistent container widths
• ✅ Embrace white space generously

Don't:

• ❌ Use absolute positioning for layout
• ❌ Forget mobile users
• ❌ Make text lines too long (65-75 characters max)
• ❌ Ignore touch target sizes
• ❌ Use fixed widths without media queries
• ❌ Cram content without spacing