Documentation

Zero-setup Tailwind and Styling

The site builder ships with zero-setup Tailwind CSS. You don't install Node, don't configure PostCSS, and don't run a build command. Create a file at /css/tailwind.css, write Tailwind utility classes in your templates, and the resulting compiled stylesheet is auto-injected on every page.

This page covers how Tailwind is enabled, how the auto-injection works, where to customize the theme and add plugins, and how to opt out if you'd rather use your own stylesheet.

Enabling Tailwind

Tailwind is enabled by the presence of /css/tailwind.css. Create the file with any content — the simplest valid setup is one line:

@import "tailwindcss";

That's it. Saving the file kicks off the compile pipeline, and from the next build forward, the compiled Tailwind stylesheet is automatically injected into every page's <head>.

Do not call link('/css/tailwind.css') from your templates. The auto-injection handles inclusion. Calling link() would emit the link tag twice.

If /css/tailwind.css doesn't exist, Tailwind is not enabled — utility classes in your templates will have no effect.

How the Auto-Injection Works

When the builder runs, it scans every template (pages/, blocks/, entries/, layouts/) for Tailwind utility classes. It collects every class found, compiles the corresponding CSS, and produces the final tailwind.css output. That compiled stylesheet is then injected into every page's <head> via a <link> tag managed by the builder.

Only utility classes that are actually used end up in the output. The compiled stylesheet is small — typically a few KB — because Tailwind's tree-shaking only includes classes the build saw.

You don't have to declare which files Tailwind should scan. The builder knows where templates live and scans them all automatically.

Customizing the Theme

The /css/tailwind.css file is also the place to customize the theme — colors, spacing, fonts, breakpoints. Tailwind v4 uses CSS-first configuration via the @theme directive:

@import "tailwindcss";

@theme {
  --color-brand: #4f46e5;
  --color-brand-light: #818cf8;
  --color-brand-dark: #3730a3;

  --font-family-display: 'Inter', system-ui, sans-serif;

  --spacing-72: 18rem;
  --spacing-84: 21rem;
}

These tokens become utility classes — bg-brand, text-brand-light, font-display, p-72. Adding a token is the entire workflow; there's no separate tailwind.config.js to maintain.

For semantic color tokens that switch with light/dark themes, declare CSS variables and reference them from @theme:

:root {
  --surface: #ffffff;
  --text: #111827;
}

:root[data-theme="dark"] {
  --surface: #0f172a;
  --text: #f8fafc;
}

@theme {
  --color-surface: var(--surface);
  --color-text: var(--text);
}

Now bg-surface and text-text will pick up the appropriate variable for the active theme.

Adding Plugins

Tailwind plugins are imported with @plugin directives in the same file:

@import "tailwindcss";
@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/typography";

The builder resolves and loads the plugin during compilation. Common Tailwind plugins (@tailwindcss/forms, @tailwindcss/typography) work out of the box; community plugins work if they're published as standard npm packages.

Custom Components and Utilities

For reusable component classes or one-off utilities, use the standard Tailwind directives:

@import "tailwindcss";

@layer components {
  .btn-primary {
    @apply inline-flex items-center px-4 py-2 rounded-lg bg-brand text-white font-medium;
    @apply hover:bg-brand-dark transition-colors;
  }
}

@layer utilities {
  .glass {
    backdrop-filter: blur(12px);
    background: rgba(255, 255, 255, 0.1);
  }
}

Anything you'd put in a normal Tailwind CSS entry file works here. The file is processed the same way Tailwind v4 processes any project's entry stylesheet.

Using Tailwind Alongside Other CSS

Tailwind is additive. You can have hand-written CSS in /css/styles.css (or any other .css file under css/) alongside Tailwind. Use link() to include those stylesheets:

<% link('/css/typography.css') %>
<% link('/css/forms.css') %>

Tailwind is still auto-injected separately. The order of the final <head> puts auto-injected Tailwind first, followed by linked stylesheets in the order they were declared. This means your own stylesheets can override Tailwind defaults without !important.

Opting Out

To use the site builder without Tailwind, simply don't create /css/tailwind.css. Utility classes won't compile, and you can use entirely hand-written CSS via link()-included stylesheets.

If you start with Tailwind and later want to remove it, deleting /css/tailwind.css disables the auto-injection — utility classes in your templates will be ignored. Replace them with regular CSS classes before deleting the file to avoid losing styling.

A Complete Example

A minimal tailwind.css for a docs site:

@import "tailwindcss";
@plugin "@tailwindcss/forms";

:root {
  --surface: #ffffff;
  --surface-elevated: #f9fafb;
  --text: #111827;
  --text-muted: #6b7280;
  --border: #e5e7eb;
  --accent: #6366f1;
}

:root[data-theme="dark"] {
  --surface: #0f172a;
  --surface-elevated: #1e293b;
  --text: #f8fafc;
  --text-muted: #94a3b8;
  --border: #334155;
  --accent: #818cf8;
}

@theme {
  --color-surface: var(--surface);
  --color-surface-elevated: var(--surface-elevated);
  --color-text: var(--text);
  --color-text-muted: var(--text-muted);
  --color-border: var(--border);
  --color-accent: var(--accent);

  --font-family-display: 'Inter', system-ui, sans-serif;
}

@layer components {
  .doc-link {
    @apply text-accent hover:underline underline-offset-2;
  }
}

Templates can then use bg-surface, text-text-muted, font-display, doc-link, and any other Tailwind utility — all without configuring a build pipeline.

What's Next