CSS Style Guide

Framework Recommendation: Tailwind CSS

For new projects, you SHOULD use Tailwind CSS⁴. It has the highest retention rate (75.5%) among CSS frameworks and provides:

• Utility-first approach with granular control
• JIT compiler that only includes used styles
• Excellent performance with minimal CSS output

Installing Tailwind CSS 4

Tailwind CSS 4⁴ splits the framework across packages: tailwindcss holds the engine and exposes no executable, and the command-line binary ships separately as @tailwindcss/cli. There is no init command, because configuration now lives in CSS rather than in a generated JavaScript file.

You MUST install both packages, pinned, for command-line builds:

npm install --save-dev tailwindcss@4.3.3 @tailwindcss/cli@4.3.3

You MUST pull the framework in with a CSS @import:

/* src/input.css */
@import "tailwindcss";

Tailwind scans your project for class names automatically. Add @source only for template directories automatic detection skips, such as anything excluded by .gitignore. Its path is resolved relative to the stylesheet, not the project root:

/* src/input.css — templates/ is listed in .gitignore */
@import "tailwindcss";
@source "../templates/**/*.html";

Build the stylesheet:

npx @tailwindcss/cli@4.3.3 -i src/input.css -o dist/output.css --minify

For Vite⁵ projects you SHOULD use the Vite plugin instead of the CLI, so Tailwind runs inside the existing build and hot-reload pipeline:

npm install --save-dev tailwindcss@4.3.3 @tailwindcss/vite@4.3.3

// vite.config.js
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

You MUST NOT use the Tailwind 3 setup. Installing tailwindcss alone creates no node_modules/.bin/tailwindcss, so npx tailwindcss@4.3.3 init fails with could not determine executable to run, and the CLI that does exist rejects the subcommand with Invalid command: init:

# Don't: installs no binary, and `init` was removed in Tailwind 4
npm install -D tailwindcss@4.3.3
npx tailwindcss@4.3.3 init

See the Tailwind CSS guide for theme tokens, utilities, and component patterns.

For projects requiring traditional CSS or component libraries, consider:

• Bulma⁶: Lightweight, Flexbox-based, beginner-friendly
• Bootstrap⁷: Extensive components, good for rapid prototyping

Linting: Stylelint

You MUST use Stylelint¹ for CSS linting.

npm install --save-dev stylelint@16.0.0 stylelint-config-standard@36.0.0

Formatting: Prettier

You MUST use Prettier² for CSS formatting.

{
  "singleQuote": true,
  "tabWidth": 2
}

Build Tools

You SHOULD use Lightning CSS¹² for production builds.

Tool	Use Case	Notes
Lightning CSS12	Production build	100x faster than PostCSS
PostCSS13	Plugin ecosystem	Still useful for specific plugins
Vite5	Development	Fast HMR, uses Lightning CSS

Preprocessors

Native CSS now supports variables and nesting. Preprocessors are OPTIONAL:

/* Native CSS nesting (production-ready 2025) */
.card {
  background: white;

  & .title {
    font-size: 1.5rem;
  }

  &:hover {
    background: #f5f5f5;
  }
}

You SHOULD use native CSS features when possible. You MAY use Sass⁸ only when you need:

• Advanced conditionals (@if, @for)
• Complex mixins
• Functions

Naming Conventions

You SHOULD use BEM¹⁴ (Block Element Modifier) or utility classes.

Dead Code: PurgeCSS

PurgeCSS³ is OPTIONAL. You SHOULD rely on your build’s own dead code elimination first and reach for PurgeCSS only where none exists. Tailwind⁴ already emits nothing but the utilities it finds in your sources, so layering PurgeCSS over a Tailwind build gains nothing and adds the risks below. Bundlers are weaker here: Vite 8⁵ keeps a stylesheet in the bundle even when the JavaScript module that imported it is tree-shaken away, because a CSS import counts as a side effect. Hand-written stylesheets and whole component libraries are where PurgeCSS earns its place.

You MUST measure the unused bytes in a production bundle before adopting PurgeCSS, and MUST NOT adopt it on the assumption that a stylesheet is wasteful.

Why measurement comes first

PurgeCSS’s default extractor treats every word in a content file as a selector. It cannot see a class name a program assembles at run time, so it deletes rules that are live in production. Given this component:

// src/app.js
const state = "success";
document.getElementById("a").className = "alert-" + state;

the extractor records alert- and state, never alert-success, and both .alert-success and .alert-error are stripped from the stylesheet. Nothing in the build fails; the page simply renders unstyled in production.

The extractor’s limitations are documented, and the framework-specific extractors that address them carry an upstream warning that they are a work in progress and not encouraged for production use. You SHOULD NOT rely on a purgecss-from-* extractor to make a purge safe. Prefer static, greppable class names in your markup, and safelist whatever remains dynamic.

Auditing before purging

You MUST run PurgeCSS in report mode before you let it write any files. --rejected lists what it would remove and writes nothing:

npx purgecss@8.0.0 --css src/app.css --content 'src/**/*.html' 'src/**/*.js' --rejected

[{"css":".static-used { color: blue; }\n","file":"src/app.css",
  "rejected":[".alert-success",".alert-error",".never-used"]}]

Review every rejected selector. Without --output, PurgeCSS prints this JSON to stdout; with it, PurgeCSS writes purged stylesheets to the given directory.

Configuration

You MUST pin PurgeCSS, MUST cover every source of markup in content — server templates and generated pages included, not just .html and .js under src/ — and MUST safelist every dynamically constructed selector:

npm install --save-dev purgecss@8.0.0

// purgecss.config.js
module.exports = {
  content: [
    './src/**/*.{html,js,ts,jsx,tsx}',
    './templates/**/*.{html,jinja,erb}',
  ],
  css: ['./build/css/*.css'],
  output: './dist/css/',
  safelist: {
    standard: ['is-active', 'has-error'],
    greedy: [/^alert-/, /^col-\d+$/],
  },
};

Read css and write output in separate directories: PurgeCSS writes each purged file under its base name, so a flat output directory collapses same-named stylesheets drawn from different source directories.

Where a rule is easier to protect at its definition than in a central list, safelist it in the stylesheet itself:

/* purgecss ignore */
.alert-success { color: green; }

Do:

// Class names are literal, so the extractor can find them
const CLASSES = { success: 'alert-success', error: 'alert-error' };
element.className = CLASSES[state];

Don’t:

// Assembled at run time; invisible to the extractor and silently purged
element.className = 'alert-' + state;

Regression testing

A purge is a change to production styling that no unit test observes. You MUST run visual and interaction regression tests against the purged bundle, not against the development build, and MUST exercise every state that reveals a dynamic class — errors, empty states, modals, and any markup rendered only after user input. See the Testing Guide for visual regression strategies.

Custom Properties

You SHOULD use CSS custom properties for design tokens:

:root {
  --color-primary: #3b82f6;
  --color-secondary: #6366f1;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --font-sans: system-ui, sans-serif;
}

.button {
  background: var(--color-primary);
  padding: var(--spacing-sm) var(--spacing-md);
}

Logical Properties

You SHOULD use logical properties for internationalization and RTL support:

/* Use logical properties for RTL support */
.card {
  margin-inline-start: 1rem;  /* Not margin-left */
  padding-block: 1rem;        /* Not padding-top/bottom */
}

Container Queries

You MAY use container queries for component-based responsive design:

.card-container {
  container-type: inline-size;
}

@container (min-width: 400px) {
  .card {
    display: flex;
  }
}