Tailwind CSS (Plain HTML/CSS) – Technical Documentation

This document describes the complete Tailwind CSS setup for a plain HTML/CSS project using the Tailwind CLI. It covers project structure, build flow, configuration, and common troubleshooting scenarios.

---

1. Project Overview

This setup uses Tailwind CSS as a build-time tool. The browser never sees Tailwind directives such as @tailwind. Instead, Tailwind compiles them into standard CSS that is linked in HTML.

---

2. Directory Structure

project-root/
├─ assets/
│  └─ css/
│     ├─ tailwind.css   ← Tailwind input (build source)
│     └─ app.css        ← Compiled output (linked in HTML)
├─ index.html
├─ package.json
├─ tailwind.config.js
└─ postcss.config.js

• tailwind.css: Contains Tailwind directives
• app.css: Generated CSS file used by the browser

---

3. Tailwind Input File

File: assets/css/tailwind.css

@tailwind base;
@tailwind components;
@tailwind utilities;

You may add custom CSS below these directives if desired.

---

4. HTML Usage

File: index.html

<link rel="stylesheet" href="assets/css/app.css">

Only the compiled CSS file (app.css) should be linked.

---

5. Tailwind Configuration

File: tailwind.config.js

module.exports = {
  content: ["./**/*.html"],
  theme: {
    extend: {},
  },
  plugins: [],
}

The content array tells Tailwind where to scan for class names. If this is incorrect, Tailwind will generate little or no CSS.

---

6. Build & Watch Scripts

File: package.json

"scripts": {
  "build": "npx @tailwindcss/cli -i ./assets/css/tailwind.css -o ./assets/css/app.css",
  "watch": "npx @tailwindcss/cli -i ./assets/css/tailwind.css -o ./assets/css/app.css --watch"
}

Commands

• npm run build – One-time CSS build
• npm run watch – Watches files and rebuilds automatically

---

7. Build Process (Technical Flow)

1. Tailwind CLI reads tailwind.css
2. Scans HTML files listed in content
3. Generates only the CSS classes that are used
4. Writes compiled CSS to assets/css/app.css
5. Browser loads app.css

---

8. Common Troubleshooting

Problem: Tailwind styles not applying

• Check that npm run watch is running
• Ensure HTML links app.css, not tailwind.css
• Verify content paths in tailwind.config.js

Problem: Output CSS is very small

This means Tailwind is not detecting your HTML files.

• Confirm file extensions are .html
• Ensure files are inside the project root
• Update content paths if files are in subfolders

Problem: npx / PowerShell execution errors

Run once as Administrator:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Problem: Changes not updating in browser

• Hard refresh (Ctrl + Shift + R)
• Confirm watch mode is running
• Ensure browser is loading the correct CSS path

---

9. Best Practices

• Do not edit compiled CSS manually
• Keep input and output files separate
• Run watch during development
• Use build for production

---

10. Verification Test

<h1 class="text-4xl font-bold text-blue-600">
  Tailwind is working
</h1>

If this renders correctly, Tailwind is fully operational.

---

End of Documentation