# Style Guide Engine Reference

The Style Guide Engine converts brand guidelines into CSS variables and design systems for presentations.

## Brand Configuration Schema

### Complete Brand Definition

```javascript
{
  "name": "Brand Name",
  "version": "1.0",
  "typography": {
    "primary": "Inter",
    "secondary": "JetBrains Mono",
    "display": "Custom Display Font",
    "weights": [300, 400, 500, 600],
    "sizes": {
      "h1": "3rem",
      "h2": "2rem", 
      "h3": "1.5rem",
      "body": "1rem",
      "caption": "0.875rem"
    },
    "line_heights": {
      "heading": 1.2,
      "body": 1.6,
      "display": 1.1
    },
    "letter_spacing": {
      "heading": "-0.02em",
      "body": "0em",
      "display": "-0.03em"
    }
  },
  "colors": {
    "primary": "#cc0000",
    "secondary": "#1a1a1a", 
    "accent": "#666666",
    "background": "#ffffff",
    "surface": "#f8f8f8",
    "text": {
      "primary": "#1a1a1a",
      "secondary": "#666666",
      "inverse": "#ffffff"
    },
    "status": {
      "success": "#22c55e",
      "warning": "#f59e0b", 
      "error": "#ef4444",
      "info": "#3b82f6"
    }
  },
  "layout": {
    "spacing": {
      "unit": "8px",
      "scale": [0.25, 0.5, 1, 1.5, 2, 3, 4, 6, 8, 12, 16],
      "container": "1200px",
      "gutter": "24px"
    },
    "borders": {
      "radius": "4px",
      "width": "1px",
      "style": "solid"
    },
    "shadows": {
      "sm": "0 1px 2px rgba(0,0,0,0.05)",
      "md": "0 4px 6px rgba(0,0,0,0.1)",
      "lg": "0 10px 15px rgba(0,0,0,0.1)"
    }
  },
  "components": {
    "slide": {
      "padding": "2rem",
      "background": "var(--color-background)",
      "min_height": "100vh"
    },
    "heading": {
      "margin_bottom": "1.5rem",
      "font_weight": 500
    },
    "content": {
      "margin_bottom": "1rem",
      "max_width": "800px"
    }
  },
  "constraints": [
    "no-gradients",
    "no-shadows",
    "no-border-radius-over-4px",
    "no-font-weight-over-500"
  ]
}
```

## CSS Variable Generation

### Python API

```python
from style_engine import StyleGuideEngine

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

# Generate from brand config
brand_config = load_brand_config('brand-config.json')
css_variables = engine.generate_css_variables(brand_config)

# Write CSS file
engine.write_css_file(css_variables, 'styles/brand-variables.css')

# Generate complete design system
engine.generate_design_system(brand_config, 'styles/')
```

### Generated CSS Structure

The engine generates organized CSS variables:

```css
/* Typography Variables */
:root {
  --font-primary: 'Inter', sans-serif;
  --font-secondary: 'JetBrains Mono', monospace;
  --font-display: 'Custom Display', serif;
  
  --font-size-h1: 3rem;
  --font-size-h2: 2rem;
  --font-size-h3: 1.5rem;
  --font-size-body: 1rem;
  --font-size-caption: 0.875rem;
  
  --font-weight-light: 300;
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  
  --line-height-heading: 1.2;
  --line-height-body: 1.6;
  --line-height-display: 1.1;
  
  --letter-spacing-heading: -0.02em;
  --letter-spacing-body: 0em;
  --letter-spacing-display: -0.03em;
}

/* Color Variables */
:root {
  --color-primary: #cc0000;
  --color-secondary: #1a1a1a;
  --color-accent: #666666;
  --color-background: #ffffff;
  --color-surface: #f8f8f8;
  
  --color-text-primary: #1a1a1a;
  --color-text-secondary: #666666;
  --color-text-inverse: #ffffff;
  
  --color-success: #22c55e;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --color-info: #3b82f6;
}

/* Layout Variables */
:root {
  --spacing-unit: 8px;
  --spacing-xs: calc(var(--spacing-unit) * 0.25);
  --spacing-sm: calc(var(--spacing-unit) * 0.5);
  --spacing-md: calc(var(--spacing-unit) * 1);
  --spacing-lg: calc(var(--spacing-unit) * 1.5);
  --spacing-xl: calc(var(--spacing-unit) * 2);
  --spacing-2xl: calc(var(--spacing-unit) * 3);
  --spacing-3xl: calc(var(--spacing-unit) * 4);
  
  --container-max-width: 1200px;
  --container-gutter: 24px;
  
  --border-radius: 4px;
  --border-width: 1px;
  
  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
  --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);
}
```

## Brand Presets

### CE Brand

```python
ce_brand = {
    "name": "CE Brand",
    "typography": {
        "primary": "Inter",
        "secondary": "JetBrains Mono",
        "weights": [300, 400, 500],
        "line_heights": {"heading": 1.3, "body": 1.6}
    },
    "colors": {
        "primary": "#cc0000",
        "black": "#1a1a1a",
        "grey": "#666666",
        "light": "#999999", 
        "border": "#eeeeee",
        "background": "#ffffff"
    },
    "constraints": [
        "no-gradients",
        "no-shadows",
        "no-border-radius-over-4px",
        "no-font-weight-over-500",
        "no-emojis-as-icons"
    ]
}
```

### PHAT Liquid Gold

```python
phat_brand = {
    "name": "PHAT Foods - Liquid Gold",
    "typography": {
        "primary": "Custom Display",
        "secondary": "Inter",
        "weights": [300, 400, 500, 600],
        "sizes": {"h1": "4rem", "h2": "2.5rem", "body": "1.1rem"}
    },
    "colors": {
        "primary": "#D4AF37",  # Liquid gold
        "secondary": "#1A1A1A",
        "accent": "#8B4513",   # Rich brown
        "background": "#FFFEF7" # Warm white
    },
    "layout": {
        "spacing": {"unit": "12px"},
        "borders": {"radius": "8px"},
        "luxury_spacing": True
    }
}
```

## Component System Generation

### Base Components

The engine generates component classes using the design system:

```css
/* Generated component styles */
.slide {
  padding: var(--spacing-2xl);
  background: var(--color-background);
  min-height: 100vh;
  display: flex;
  flex-direction: column;
  justify-content: center;
}

.slide-title {
  text-align: center;
  padding: var(--spacing-3xl) var(--spacing-xl);
}

.slide-title .headline {
  font-family: var(--font-display, var(--font-primary));
  font-size: var(--font-size-h1);
  font-weight: var(--font-weight-medium);
  line-height: var(--line-height-display);
  letter-spacing: var(--letter-spacing-display);
  color: var(--color-text-primary);
  margin-bottom: var(--spacing-lg);
}

.slide-title .subline {
  font-family: var(--font-primary);
  font-size: var(--font-size-h3);
  color: var(--color-text-secondary);
  font-weight: var(--font-weight-normal);
}
```

### Responsive Components

```css
/* Responsive design system */
.slide-content {
  max-width: var(--container-max-width);
  margin: 0 auto;
  padding: 0 var(--container-gutter);
}

@media (max-width: 768px) {
  .slide {
    padding: var(--spacing-xl);
  }
  
  .slide-title .headline {
    font-size: calc(var(--font-size-h1) * 0.75);
  }
}

@media (max-width: 480px) {
  .slide {
    padding: var(--spacing-lg);
  }
  
  .slide-title .headline {
    font-size: calc(var(--font-size-h1) * 0.6);
  }
}
```

## Advanced Features

### Dynamic Color Schemes

Generate multiple color schemes from brand colors:

```python
# Generate color variations
engine.generate_color_scheme(base_color="#cc0000", scheme_type="monochromatic")
engine.generate_color_scheme(base_color="#cc0000", scheme_type="complementary")
engine.generate_color_scheme(base_color="#cc0000", scheme_type="triadic")
```

### Accessibility Compliance

Automatically ensure accessibility standards:

```python
# Configure accessibility requirements
engine.set_accessibility_config({
    "min_contrast_ratio": 4.5,  # WCAG AA
    "focus_indicators": True,
    "color_blind_safe": True,
    "large_text_support": True
})

# Validate color combinations
engine.validate_color_contrast("#cc0000", "#ffffff")  # Returns contrast ratio
```

### Custom CSS Properties

Generate custom properties for advanced layouts:

```python
# Configure custom properties
engine.add_custom_properties({
    "slide-aspect-ratio": "16/9",
    "content-animation-duration": "0.3s",
    "slide-transition-timing": "ease-out"
})
```

## CLI Usage

### Generate Brand System

```bash
# Generate from brand config
python scripts/engines/style_engine.py project-path \
  --config styles/brand-config.json \
  --output styles/brand-system.css

# Generate with specific preset
python scripts/engines/style_engine.py project-path \
  --preset ce \
  --output styles/ce-system.css

# Generate complete design system
python scripts/engines/style_engine.py project-path \
  --config styles/brand-config.json \
  --complete-system styles/
```

### Apply Brand Guidelines

```bash
# Apply CE brand
python scripts/apply_brand.py project-path --brand ce

# Apply PHAT liquid gold
python scripts/apply_brand.py project-path --brand phat --theme liquid-gold

# Apply custom brand
python scripts/apply_brand.py project-path \
  --config custom-brand.json \
  --output styles/custom-system.css
```

### Validate Brand Compliance

```bash
# Check generated styles against brand constraints
python scripts/engines/style_engine.py project-path \
  --validate \
  --config styles/brand-config.json \
  --check-file styles/custom.css

# Generate compliance report
python scripts/engines/style_engine.py project-path \
  --compliance-report \
  --output compliance-report.json
```

## Integration with Layout Engine

The Style Guide Engine works with the Layout Engine for complete control:

```python
# Generate styles for specific layout
layout_config = {
    "type": "split-screen",
    "text_width": "60%", 
    "image_width": "40%"
}

css_styles = engine.generate_layout_styles(layout_config, brand_config)
```

## Error Handling

```python
try:
    engine.generate_css_variables(invalid_config)
except BrandConfigError as e:
    print(f"Invalid brand configuration: {e.field}")
    
try:
    engine.validate_color_contrast("#ffffff", "#fffffa")  # Poor contrast
except AccessibilityError as e:
    print(f"Accessibility violation: {e.message}")
    print(f"Current contrast: {e.contrast_ratio}")
    print(f"Required: {e.required_ratio}")
```

## Performance Optimization

### CSS Variable Optimization

```python
# Configure optimization
engine.set_optimization({
    "combine_similar_values": True,
    "remove_unused_variables": True,
    "minify_output": True,
    "generate_fallbacks": True
})

# Generate optimized CSS
optimized_css = engine.generate_optimized_css(brand_config)
```

### Caching

```python
# Enable style generation caching
engine.enable_cache({
    "cache_dir": ".cache/styles",
    "invalidate_on_config_change": True,
    "max_age_hours": 24
})
```