folderweb/docs/02-tutorial/02-styling.md

# Styling

FolderWeb uses modern CSS — no preprocessors, no build steps. Edit CSS files directly and refresh.

## Where Styles Live

```
custom/
└── styles/
    └── base.css           # Your main stylesheet
```

Page-specific styles can be placed alongside content:

```
content/portfolio/
├── index.md
└── styles.css             # Loaded only on this page
```

**Loading order:**
1. `custom/styles/base.css` — always loaded
2. Page-specific `styles.css` — if present in the content directory

## Editing the Main Stylesheet

Edit `custom/styles/base.css` for site-wide styles:

```css
:root {
  --color-primary: oklch(60% 0.15 250);
  --color-text: oklch(20% 0 0);
  --color-bg: oklch(98% 0 0);
  --font-base: system-ui, -apple-system, sans-serif;
  --font-mono: 'SF Mono', Monaco, monospace;
}

body {
  font-family: var(--font-base);
  color: var(--color-text);
  background: var(--color-bg);
  line-height: 1.6;
}
```

## CSS Variables

Define design tokens as variables, use them throughout:

```css
:root {
  --color-accent: oklch(65% 0.2 150);
  --radius-sm: 0.25rem;
  --shadow: 0 2px 8px oklch(0% 0 0 / 0.1);
}

.button {
  background: var(--color-accent);
  border-radius: var(--radius-sm);
  box-shadow: var(--shadow);
}
```

## OKLCH Colors

FolderWeb's default styles use OKLCH for perceptually uniform colors:

```css
--color: oklch(65% 0.1 250);
```

Format: `oklch(lightness chroma hue / alpha)`
- **Lightness:** 0% (black) to 100% (white)
- **Chroma:** 0 (gray) to ~0.4 (vivid)
- **Hue:** 0–360 degrees

## CSS Nesting

Nest related styles without a preprocessor:

```css
.card {
  padding: 1rem;

  & h2 {
    margin-top: 0;
  }

  & p {
    color: var(--color-text-muted);
  }

  &:hover {
    box-shadow: var(--shadow-lg);
  }
}
```

## Fluid Typography

Responsive sizing without media queries:

```css
h1 {
  font-size: clamp(2rem, 5vw, 4rem);
}
```

## Grid Layout

```css
.page-layout {
  display: grid;
  grid-template-columns: 1fr min(65ch, 100%) 1fr;
  gap: 2rem;

  & > * {
    grid-column: 2;
  }

  & > .full-width {
    grid-column: 1 / -1;
  }
}
```

## Classless CSS

FolderWeb defaults to styling HTML elements directly rather than relying on classes. Since content comes from Markdown and HTML files, this means most content is styled without any classes:

```css
article {
  max-width: 65ch;
  margin: 0 auto;

  & h1 {
    font-size: 2.5rem;
    margin-bottom: 1rem;
  }

  & p {
    line-height: 1.7;
  }
}
```

Use classes when you need component variants, JavaScript hooks, or utility overrides.

## Page-Specific Styles

Add a `styles.css` file to a content directory:

```
content/portfolio/
├── index.md
└── styles.css
```

```css
.portfolio-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 2rem;
}
```

FolderWeb loads it automatically with cache-busting:

```html
<link rel="stylesheet" href="/portfolio/styles.css?v=abc123">
```

## Page-Specific Scripts

Add a `script.js` file to a content directory for progressive enhancement:

```
content/portfolio/
├── index.md
└── script.js
```

Loaded automatically with `defer`:

```html
<script defer src="/portfolio/script.js?v=abc123"></script>
```

## Dark Mode

Use CSS variables with `prefers-color-scheme`:

```css
:root {
  --color-bg: oklch(98% 0 0);
  --color-text: oklch(20% 0 0);
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: oklch(15% 0 0);
    --color-text: oklch(95% 0 0);
  }
}
```

## Responsive Design

Prefer fluid CSS over fixed breakpoints:

```css
.container {
  width: min(90%, 1200px);
  padding: clamp(1rem, 3vw, 3rem);
}

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(300px, 100%), 1fr));
  gap: clamp(1rem, 3vw, 2rem);
}
```

Use media queries only when layout needs to change fundamentally (e.g., sidebar position).

## Cache Busting

FolderWeb versions CSS files with MD5 hashes automatically:

```html
<link rel="stylesheet" href="/custom/styles/base.css?v=a1b2c3d4">
```

When you edit your CSS, the hash changes and browsers fetch the new version.

## Next Steps

- [Templates](03-templates.md) — Control HTML structure and layout
- [Internationalization](../03-reference/04-internationalization.md) — Multi-language support