# Layout Engine Reference

The Layout Engine provides granular control over slide layouts, positioning, and responsive behavior.

## Layout Types

### Title Layout

Center-aligned title slides with full control over positioning:

```css
.layout-title {
  display: flex;
  flex-direction: column;
  justify-content: var(--title-vertical-align, center);
  align-items: var(--title-horizontal-align, center);
  text-align: var(--title-text-align, center);
  padding: var(--title-padding, var(--spacing-3xl));
  min-height: var(--slide-min-height, 100vh);
}

.layout-title .headline {
  font-size: var(--title-headline-size, var(--font-size-h1));
  margin-bottom: var(--title-headline-spacing, var(--spacing-lg));
  max-width: var(--title-max-width, 800px);
}

.layout-title .subline {
  font-size: var(--title-subline-size, var(--font-size-h3));
  color: var(--title-subline-color, var(--color-text-secondary));
}
```

### Content Layout

Single-column content with precise typography control:

```css
.layout-content {
  display: grid;
  grid-template-columns: 1fr;
  gap: var(--content-gap, var(--spacing-xl));
  padding: var(--content-padding, var(--spacing-2xl));
  max-width: var(--content-max-width, var(--container-max-width));
  margin: 0 auto;
}

.layout-content .headline {
  font-size: var(--content-headline-size, var(--font-size-h2));
  margin-bottom: var(--content-headline-spacing, var(--spacing-md));
}

.layout-content .body {
  font-size: var(--content-body-size, var(--font-size-body));
  line-height: var(--content-line-height, var(--line-height-body));
  margin-bottom: var(--content-body-spacing, var(--spacing-lg));
}

.layout-content .bullets {
  list-style: var(--content-bullet-style, disc);
  margin-left: var(--content-bullet-indent, var(--spacing-lg));
}

.layout-content .bullets li {
  margin-bottom: var(--content-bullet-spacing, var(--spacing-sm));
}
```

### Split Layout

Two-column layouts with customizable ratios:

```css
.layout-split {
  display: grid;
  grid-template-columns: var(--split-ratio, 1fr 1fr);
  gap: var(--split-gap, var(--spacing-2xl));
  align-items: var(--split-vertical-align, center);
  padding: var(--split-padding, var(--spacing-xl));
  min-height: var(--slide-min-height, 100vh);
}

.layout-split-60-40 {
  grid-template-columns: 60% 40%;
}

.layout-split-70-30 {
  grid-template-columns: 70% 30%;
}

.layout-split-40-60 {
  grid-template-columns: 40% 60%;
}

.layout-split .text-content {
  padding: var(--split-text-padding, var(--spacing-lg));
}

.layout-split .image-content {
  display: flex;
  align-items: var(--split-image-align, center);
  justify-content: var(--split-image-justify, center);
}

.layout-split .image-content img {
  max-width: 100%;
  height: auto;
  object-fit: var(--split-image-fit, contain);
}
```

### Grid Layout

Multi-element grid layouts for complex content:

```css
.layout-grid {
  display: grid;
  grid-template-columns: var(--grid-columns, repeat(2, 1fr));
  gap: var(--grid-gap, var(--spacing-lg));
  padding: var(--grid-padding, var(--spacing-xl));
}

.layout-grid-3col {
  grid-template-columns: repeat(3, 1fr);
}

.layout-grid-4col {
  grid-template-columns: repeat(4, 1fr);
}

.layout-grid .grid-item {
  padding: var(--grid-item-padding, var(--spacing-md));
  background: var(--grid-item-background, transparent);
  border: var(--grid-item-border, none);
  border-radius: var(--border-radius);
}

.layout-grid .grid-item.featured {
  grid-column: span var(--featured-span, 2);
}
```

## Layout API

### Python API

```python
from layout_engine import LayoutEngine

# Initialize
engine = LayoutEngine('/path/to/project')

# Define layout configuration
layout_config = {
    "type": "split",
    "ratio": "60-40",
    "text_side": "left",
    "vertical_align": "center",
    "gap": "2rem",
    "responsive": True
}

# Generate layout CSS
layout_css = engine.generate_layout(layout_config)

# Apply layout to slide
engine.apply_layout_to_slide("slide-5", layout_config)

# Generate responsive variants
responsive_css = engine.generate_responsive_layout(layout_config)
```

### Custom Layout Creation

```python
# Create custom layout
custom_layout = {
    "name": "hero-cta",
    "css": {
        "display": "flex",
        "flex-direction": "column",
        "justify-content": "space-between",
        "min-height": "100vh"
    },
    "components": {
        "hero": {
            "flex": "1",
            "display": "flex",
            "align-items": "center",
            "justify-content": "center"
        },
        "cta": {
            "text-align": "center",
            "padding": "2rem"
        }
    }
}

engine.register_custom_layout(custom_layout)
```

## Responsive Design

### Breakpoint System

```css
/* Mobile-first responsive system */
:root {
  --breakpoint-xs: 320px;
  --breakpoint-sm: 480px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1200px;
  --breakpoint-2xl: 1440px;
}

/* Default mobile styles */
.layout-split {
  grid-template-columns: 1fr;
  gap: var(--spacing-lg);
}

.layout-split .text-content {
  order: var(--mobile-text-order, 1);
}

.layout-split .image-content {
  order: var(--mobile-image-order, 2);
}

/* Tablet styles */
@media (min-width: 768px) {
  .layout-split {
    grid-template-columns: var(--split-ratio, 1fr 1fr);
  }
}

/* Desktop styles */
@media (min-width: 1024px) {
  .layout-split {
    gap: var(--split-gap, var(--spacing-2xl));
  }
}
```

### Dynamic Responsive Configuration

```python
# Configure responsive behavior
responsive_config = {
    "mobile": {
        "max_width": "768px",
        "layout": "stack",
        "font_scale": 0.875,
        "spacing_scale": 0.75
    },
    "tablet": {
        "min_width": "768px",
        "max_width": "1024px", 
        "layout": "hybrid",
        "font_scale": 0.9,
        "spacing_scale": 0.875
    },
    "desktop": {
        "min_width": "1024px",
        "layout": "full",
        "font_scale": 1.0,
        "spacing_scale": 1.0
    }
}

engine.generate_responsive_css(responsive_config)
```

## Typography Control

### Precise Typography Layouts

```css
.typography-control {
  /* Font sizing */
  --heading-size: var(--custom-heading-size, var(--font-size-h2));
  --body-size: var(--custom-body-size, var(--font-size-body));
  
  /* Line height control */
  --heading-line-height: var(--custom-heading-lh, 1.2);
  --body-line-height: var(--custom-body-lh, 1.6);
  
  /* Letter spacing */
  --heading-letter-spacing: var(--custom-heading-ls, -0.02em);
  --body-letter-spacing: var(--custom-body-ls, 0em);
  
  /* Paragraph spacing */
  --paragraph-spacing: var(--custom-para-spacing, 1.5em);
  
  /* Text alignment */
  --text-align: var(--custom-text-align, left);
  
  /* Text width and measures */
  --text-max-width: var(--custom-text-width, 65ch);
  --text-indent: var(--custom-text-indent, 0);
}
```

### Font Loading and Performance

```css
/* Font display optimization */
@font-face {
  font-family: 'Custom Display';
  src: url('assets/fonts/custom-display.woff2') format('woff2');
  font-display: swap;
  font-weight: 300 600;
}

/* Font loading states */
.font-loading .text {
  font-family: var(--font-fallback, Arial, sans-serif);
}

.font-loaded .text {
  font-family: var(--font-primary);
}
```

## Spacing System

### Modular Spacing Scale

```python
# Generate spacing system
spacing_config = {
    "base_unit": "8px",
    "scale": [0.25, 0.5, 0.75, 1, 1.25, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10, 12, 16],
    "semantic_names": {
        "xs": 0.25,
        "sm": 0.5, 
        "md": 1,
        "lg": 1.5,
        "xl": 2,
        "2xl": 3,
        "3xl": 4
    }
}

spacing_css = engine.generate_spacing_system(spacing_config)
```

### Contextual Spacing

```css
/* Content-aware spacing */
.layout-content {
  /* Vertical rhythm */
  --content-rhythm: var(--spacing-lg);
}

.layout-content > * + * {
  margin-top: var(--content-rhythm);
}

.layout-content h2 + p {
  margin-top: var(--spacing-sm); /* Tighter after headings */
}

.layout-content p + ul {
  margin-top: var(--spacing-xs); /* Tighter before lists */
}

/* Slide-specific spacing */
.slide:first-child {
  padding-top: var(--spacing-3xl); /* Extra space on first slide */
}

.slide:last-child {
  padding-bottom: var(--spacing-3xl); /* Extra space on last slide */
}
```

## Animation and Transitions

### Slide Transitions

```css
.slide {
  transition-property: transform, opacity;
  transition-duration: var(--slide-transition-duration, 0.5s);
  transition-timing-function: var(--slide-transition-easing, ease-out);
}

/* Slide transition types */
.transition-fade {
  opacity: 0;
}

.transition-fade.active {
  opacity: 1;
}

.transition-slide-left {
  transform: translateX(-100%);
}

.transition-slide-left.active {
  transform: translateX(0);
}

.transition-zoom {
  transform: scale(0.8);
  opacity: 0;
}

.transition-zoom.active {
  transform: scale(1);
  opacity: 1;
}
```

### Content Animations

```css
/* Staggered content animations */
.slide.active .animate-in {
  animation: slideInUp 0.6s ease-out forwards;
}

.slide.active .animate-in:nth-child(1) {
  animation-delay: 0.1s;
}

.slide.active .animate-in:nth-child(2) {
  animation-delay: 0.2s;
}

.slide.active .animate-in:nth-child(3) {
  animation-delay: 0.3s;
}

@keyframes slideInUp {
  from {
    transform: translateY(30px);
    opacity: 0;
  }
  to {
    transform: translateY(0);
    opacity: 1;
  }
}
```

## CLI Usage

### Generate Layout

```bash
# Generate specific layout
python scripts/engines/layout_engine.py project-path \
  --layout split \
  --ratio 60-40 \
  --output styles/split-layout.css

# Generate responsive layout system
python scripts/engines/layout_engine.py project-path \
  --responsive-system \
  --output styles/responsive-layouts.css

# Apply layout to slides
python scripts/engines/layout_engine.py project-path \
  --apply-layout split \
  --slides slide-1,slide-3,slide-5
```

### Custom Layout Creation

```bash
# Create custom layout from config
python scripts/engines/layout_engine.py project-path \
  --create-custom custom-layout.json \
  --output styles/custom.css

# Generate layout variants
python scripts/engines/layout_engine.py project-path \
  --layout split \
  --variants "50-50,60-40,70-30" \
  --output styles/split-variants.css
```

## Performance Optimization

### CSS Grid Optimization

```css
/* Optimized grid layouts */
.layout-grid {
  display: grid;
  grid-template-columns: repeat(var(--grid-cols, 2), 1fr);
  gap: var(--grid-gap);
  
  /* Performance optimizations */
  contain: layout style;
  will-change: transform;
}

/* Subgrid support (where available) */
@supports (grid-template-columns: subgrid) {
  .layout-nested-grid {
    grid-template-columns: subgrid;
  }
}
```

### Layout Shift Prevention

```css
/* Prevent cumulative layout shift */
.slide img {
  width: 100%;
  height: auto;
  aspect-ratio: var(--image-aspect-ratio, 16/9);
  object-fit: cover;
}

.slide .content-placeholder {
  min-height: var(--content-min-height, 200px);
}
```

## Integration Examples

### With Style Guide Engine

```python
# Generate coordinated layout + style system
brand_config = load_brand_config('brand.json')
layout_config = {
    "spacing_unit": brand_config["layout"]["spacing"]["unit"],
    "max_width": brand_config["layout"]["spacing"]["container"],
    "typography": brand_config["typography"]
}

combined_css = engine.generate_integrated_system(brand_config, layout_config)
```

### With Content API

```python
# Apply layout based on content type
content = content_api.load_content()
for slide in content["slides"]:
    layout = engine.suggest_layout(slide["content"], slide["type"])
    engine.apply_layout_to_slide(slide["id"], layout)
```