# CSS Variables Reference

Complete reference for all CSS custom properties available in FolderWeb.

## Overview

FolderWeb uses CSS custom properties (variables) for theming. Override these in `/custom/styles/base.css` to customize your site's appearance.

## Color Variables

### Primary Colors

```css
:root {
    --color-primary: oklch(0.65 0.15 250);
    --color-secondary: oklch(0.50 0.12 250);
    --color-light: oklch(0.97 0.01 250);
    --color-grey: oklch(0.37 0 0);
}
```

| Variable | Default | Description |
|----------|---------|-------------|
| `--color-primary` | Blue (OKLCH) | Primary brand color, links, buttons |
| `--color-secondary` | Dark blue (OKLCH) | Secondary accents, hover states |
| `--color-light` | Off-white (OKLCH) | Background, light sections |
| `--color-grey` | Dark grey | Body text, headings |

### OKLCH Color Space

FolderWeb uses OKLCH for perceptually uniform colors:

```css
oklch(lightness chroma hue)
```

- **Lightness**: 0 (black) to 1 (white)
- **Chroma**: 0 (grey) to ~0.4 (vibrant)
- **Hue**: 0-360 degrees

**Examples**:
```css
/* Blue hues (250°) */
--color-primary: oklch(0.65 0.15 250);

/* Orange hues (30°) */
--color-primary: oklch(0.65 0.20 30);

/* Green hues (150°) */
--color-primary: oklch(0.60 0.15 150);

/* Red hues (0°) */
--color-primary: oklch(0.60 0.20 0);

/* Purple hues (300°) */
--color-primary: oklch(0.60 0.18 300);
```

### Alternative Color Formats

You can use hex, rgb, or hsl instead:

```css
:root {
    /* Hex */
    --color-primary: #4169E1;
    --color-secondary: #1E3A8A;
    
    /* RGB */
    --color-primary: rgb(65, 105, 225);
    --color-secondary: rgb(30, 58, 138);
    
    /* HSL */
    --color-primary: hsl(225, 73%, 57%);
    --color-secondary: hsl(225, 64%, 33%);
}
```

## Typography Variables

### Font Families

```css
:root {
    --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
    --font-heading: Georgia, "Times New Roman", serif;
}
```

| Variable | Default | Description |
|----------|---------|-------------|
| `--font-body` | System sans-serif stack | Body text, paragraphs |
| `--font-heading` | Serif stack | Headings (h1-h6) |

**Custom Fonts**:
```css
@font-face {
    font-family: 'MyFont';
    src: url('/custom/fonts/MyFont.woff2') format('woff2');
    font-weight: 400;
    font-style: normal;
    font-display: swap;
}

:root {
    --font-body: 'MyFont', sans-serif;
}
```

### Font Sizes

```css
:root {
    --font-size-base: 1.125rem;     /* 18px */
    --font-size-small: 0.875rem;    /* 14px */
}
```

| Variable | Default | Description |
|----------|---------|-------------|
| `--font-size-base` | 1.125rem (18px) | Body text size |
| `--font-size-small` | 0.875rem (14px) | Small text, metadata |

**Responsive Sizing**:
```css
:root {
    /* Fluid typography */
    --font-size-base: clamp(1rem, 0.9rem + 0.5vw, 1.25rem);
}

h1 {
    font-size: clamp(2rem, 1.5rem + 2vw, 3.5rem);
}
```

### Line Heights

```css
:root {
    --line-height-base: 1.6;
    --line-height-heading: 1.2;
}
```

| Variable | Default | Description |
|----------|---------|-------------|
| `--line-height-base` | 1.6 | Body text line height |
| `--line-height-heading` | 1.2 | Heading line height |

## Spacing Variables

```css
:root {
    --spacing-unit: 1.5rem;         /* 24px */
    --spacing-small: 0.75rem;       /* 12px */
    --spacing-large: 3rem;          /* 48px */
}
```

| Variable | Default | Description |
|----------|---------|-------------|
| `--spacing-unit` | 1.5rem (24px) | Base spacing unit |
| `--spacing-small` | 0.75rem (12px) | Small gaps |
| `--spacing-large` | 3rem (48px) | Large gaps, section spacing |

**Usage**:
```css
.card {
    padding: var(--spacing-unit);
    margin-block-end: var(--spacing-large);
}

.tag {
    padding: var(--spacing-small);
}
```

**Responsive Spacing**:
```css
:root {
    --spacing-unit: clamp(1rem, 0.8rem + 1vw, 2rem);
}
```

## Layout Variables

```css
:root {
    --max-width: 70rem;             /* 1120px */
    --border-radius: 4px;
}
```

| Variable | Default | Description |
|----------|---------|-------------|
| `--max-width` | 70rem (1120px) | Content max-width |
| `--border-radius` | 4px | Corner rounding |

**Usage**:
```css
.contain {
    max-inline-size: var(--max-width);
    margin-inline: auto;
}

.card {
    border-radius: var(--border-radius);
}
```

## Complete Variable List

```css
:root {
    /* Colors */
    --color-primary: oklch(0.65 0.15 250);
    --color-secondary: oklch(0.50 0.12 250);
    --color-light: oklch(0.97 0.01 250);
    --color-grey: oklch(0.37 0 0);
    
    /* Typography */
    --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
    --font-heading: Georgia, "Times New Roman", serif;
    --font-size-base: 1.125rem;
    --font-size-small: 0.875rem;
    --line-height-base: 1.6;
    --line-height-heading: 1.2;
    
    /* Spacing */
    --spacing-unit: 1.5rem;
    --spacing-small: 0.75rem;
    --spacing-large: 3rem;
    
    /* Layout */
    --max-width: 70rem;
    --border-radius: 4px;
}
```

## Customization Examples

### Orange Theme

```css
:root {
    --color-primary: oklch(0.65 0.20 30);
    --color-secondary: oklch(0.50 0.18 30);
    --color-light: oklch(0.97 0.01 30);
}
```

### Dark Mode

```css
@media (prefers-color-scheme: dark) {
    :root {
        --color-primary: oklch(0.70 0.15 250);
        --color-secondary: oklch(0.80 0.12 250);
        --color-light: oklch(0.25 0 0);
        --color-grey: oklch(0.90 0 0);
    }
}
```

### Large Text

```css
:root {
    --font-size-base: 1.25rem;      /* 20px */
    --line-height-base: 1.7;
    --spacing-unit: 2rem;
}
```

### Tight Layout

```css
:root {
    --max-width: 50rem;             /* 800px */
    --spacing-unit: 1rem;           /* 16px */
    --spacing-large: 2rem;          /* 32px */
}
```

### Rounded Design

```css
:root {
    --border-radius: 12px;
}
```

## Using Variables

### In Your Styles

```css
.card {
    background: var(--color-light);
    color: var(--color-grey);
    padding: var(--spacing-unit);
    border-radius: var(--border-radius);
}

.button {
    background: var(--color-primary);
    color: white;
    padding: var(--spacing-small) var(--spacing-unit);
    border-radius: var(--border-radius);
}

.button:hover {
    background: var(--color-secondary);
}
```

### With Fallbacks

Provide fallbacks for older browsers:

```css
.card {
    background: #F5F5F5;                        /* Fallback */
    background: var(--color-light);             /* Variable */
}
```

### With calc()

Combine with calculations:

```css
.card {
    padding: calc(var(--spacing-unit) * 2);
    margin-block-end: calc(var(--spacing-large) - 1rem);
}
```

### With color-mix()

Create variations:

```css
.button {
    background: var(--color-primary);
}

.button:hover {
    background: color-mix(in oklch, var(--color-primary), black 10%);
}

.button-light {
    background: color-mix(in oklch, var(--color-primary), white 80%);
}
```

## Adding Custom Variables

Define your own variables:

```css
:root {
    /* Custom color palette */
    --color-accent: oklch(0.70 0.15 180);
    --color-warning: oklch(0.70 0.20 60);
    --color-danger: oklch(0.60 0.20 10);
    --color-success: oklch(0.65 0.15 140);
    
    /* Custom spacing */
    --spacing-xs: 0.25rem;
    --spacing-xl: 4rem;
    --spacing-2xl: 6rem;
    
    /* Custom typography */
    --font-mono: 'Monaco', 'Courier New', monospace;
    --font-size-large: 1.5rem;
    --font-size-xlarge: 2rem;
    
    /* Custom layout */
    --sidebar-width: 20rem;
    --header-height: 4rem;
    --content-gap: 2rem;
}
```

Use them:

```css
.sidebar {
    width: var(--sidebar-width);
    background: var(--color-light);
}

code {
    font-family: var(--font-mono);
    background: var(--color-accent);
    padding: var(--spacing-xs);
}
```

## Scoped Variables

Override variables for specific sections:

```css
/* Global defaults */
:root {
    --color-primary: oklch(0.65 0.15 250);
}

/* Blog section uses green */
.section-blog {
    --color-primary: oklch(0.60 0.15 150);
}

/* About page uses orange */
.page-about {
    --color-primary: oklch(0.65 0.20 30);
}

/* Variables cascade to children */
.section-blog .button {
    background: var(--color-primary);  /* Green in blog */
}
```

## Responsive Variables

Change variables at breakpoints:

```css
:root {
    --spacing-unit: 1rem;
    --font-size-base: 1rem;
    --max-width: 60rem;
}

@media (min-width: 768px) {
    :root {
        --spacing-unit: 1.5rem;
        --font-size-base: 1.125rem;
        --max-width: 70rem;
    }
}

@media (min-width: 1200px) {
    :root {
        --spacing-unit: 2rem;
        --font-size-base: 1.25rem;
        --max-width: 80rem;
    }
}
```

## Browser Support

CSS custom properties are supported in all modern browsers:
- Chrome 49+
- Firefox 31+
- Safari 9.1+
- Edge 15+

For older browsers, provide fallbacks or use PostCSS with custom properties plugin.

## Debugging Variables

Inspect variables in browser DevTools:

1. Right-click element → Inspect
2. Check "Computed" tab
3. Scroll to custom properties section
4. See resolved values

Or log in console:

```javascript
getComputedStyle(document.documentElement).getPropertyValue('--color-primary')
```

## Best Practices

### Use Semantic Names

```css
/* Good - semantic */
--color-primary
--color-text
--color-background

/* Avoid - non-semantic */
--color-blue
--color-444
```

### Group Related Variables

```css
:root {
    /* Colors */
    --color-primary: ...;
    --color-secondary: ...;
    
    /* Typography */
    --font-body: ...;
    --font-heading: ...;
    
    /* Spacing */
    --spacing-unit: ...;
}
```

### Document Your Variables

```css
:root {
    /* Brand colors from design system */
    --color-primary: oklch(0.65 0.15 250);  /* Blue - primary CTA */
    --color-secondary: oklch(0.50 0.12 250); /* Dark blue - accents */
    
    /* Layout constraints */
    --max-width: 70rem;  /* 1120px - content max width */
}
```

### Provide Fallbacks

```css
.card {
    background: #F5F5F5;
    background: var(--color-light);
}
```

## Related

- [Custom Styles Guide](../how-to/custom-styles.md)
- [Template Reference](templates.md)
- [File Structure Reference](file-structure.md)