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:

: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:

: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:

--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:

.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:

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

Grid Layout

.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:

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

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

FolderWeb loads it automatically with cache-busting:

<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:

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

Dark Mode

Use CSS variables with prefers-color-scheme:

: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:

.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:

<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 — Control HTML structure and layout
• Internationalization — Multi-language support