0
# Tailwind CSS
1

2
Tailwind CSS is a utility-first CSS framework that provides low-level utility classes for building custom user interfaces directly in HTML markup. It features a comprehensive design system with customizable themes, a powerful JIT (Just-in-Time) compiler, and a modern plugin architecture for extending functionality.
3

4
## Package Information
5

6
- **Package Name**: tailwindcss
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install tailwindcss`
10

11
## Core Imports
12

13
Main compilation API:
14

15
```typescript
16
import { compile, compileAst } from "tailwindcss";
17
```
18

19
Plugin creation:
20

21
```typescript
22
import plugin from "tailwindcss/plugin";
23
```
24

25
Theme system:
26

27
```typescript
28
import colors from "tailwindcss/colors";
29
import defaultTheme from "tailwindcss/defaultTheme";
30
import flattenColorPalette from "tailwindcss/lib/util/flattenColorPalette";
31
```
32

33
AST processing:
34

35
```typescript
36
import { 
37
  toCss, walk, WalkAction,
38
  rule, atRule, styleRule, decl, comment, context, atRoot,
39
  optimizeAst
40
} from "tailwindcss";
41
```
42

43
For CommonJS:
44

45
```javascript
46
const { compile, compileAst, toCss, walk, rule, styleRule, decl } = require("tailwindcss");
47
const plugin = require("tailwindcss/plugin");
48
const colors = require("tailwindcss/colors");
49
const defaultTheme = require("tailwindcss/defaultTheme");
50
const flattenColorPalette = require("tailwindcss/lib/util/flattenColorPalette");
51
```
52

53
## Basic Usage
54

55
```typescript
56
import { compile } from "tailwindcss";
57

58
// Basic CSS compilation
59
const css = `
60
  @theme {
61
    --color-primary: blue;
62
  }
63
  
64
  @tailwind utilities;
65
`;
66

67
const result = await compile(css);
68
const compiled = result.build(["bg-primary", "text-white"]);
69
console.log(compiled);
70

71
// Plugin creation
72
import plugin from "tailwindcss/plugin";
73

74
const myPlugin = plugin(function({ addUtilities }) {
75
  addUtilities({
76
    '.my-utility': {
77
      'custom-property': 'value',
78
    },
79
  });
80
});
81
```
82

83
## Architecture
84

85
Tailwind CSS is built around several key components:
86

87
- **Compilation Engine**: Core CSS processing and utility generation (`compile`, `compileAst`)
88
- **Plugin System**: Extensible architecture for custom utilities, variants, and components
89
- **Design System**: Theme management with CSS custom properties and design tokens
90
- **AST Processing**: Low-level CSS abstract syntax tree manipulation
91
- **Compatibility Layer**: Backward compatibility with v3 API and patterns
92
- **JIT Compiler**: Just-in-time generation of CSS utilities based on usage
93

94
## Capabilities
95

96
### CSS Compilation
97

98
Core CSS compilation functionality for processing Tailwind directives and generating utility classes. Handles theme processing, utility generation, and optimization.
99

100
```typescript { .api }
101
function compile(
102
  css: string,
103
  opts?: CompileOptions
104
): Promise<{
105
  sources: { base: string; pattern: string; negated: boolean }[];
106
  root: Root;
107
  features: Features;
108
  build(candidates: string[]): string;
109
  buildSourceMap(): DecodedSourceMap;
110
}>;
111

112
interface CompileOptions {
113
  base?: string;
114
  from?: string;
115
  polyfills?: Polyfills;
116
  loadModule?: (
117
    id: string,
118
    base: string,
119
    resourceHint: 'plugin' | 'config'
120
  ) => Promise<{
121
    path: string;
122
    base: string;
123
    module: Plugin | Config;
124
  }>;
125
  loadStylesheet?: (
126
    id: string,
127
    base: string
128
  ) => Promise<{
129
    path: string;
130
    base: string;
131
    content: string;
132
  }>;
133
}
134
```
135

136
[CSS Compilation](./compilation.md)
137

138
### Plugin Development
139

140
Plugin system for extending Tailwind CSS with custom utilities, variants, and components. Provides a rich API for adding functionality.
141

142
```typescript { .api }
143
function plugin(handler: PluginFn, config?: Partial<Config>): PluginWithConfig;
144

145
interface PluginAPI {
146
  addBase(base: CssInJs): void;
147
  addVariant(name: string, variant: string | string[] | CssInJs): void;
148
  matchVariant<T>(
149
    name: string,
150
    cb: (value: T | string, extra: { modifier: string | null }) => string | string[],
151
    options?: {
152
      values?: Record<string, T>;
153
      sort?(
154
        a: { value: T | string; modifier: string | null },
155
        b: { value: T | string; modifier: string | null }
156
      ): number;
157
    }
158
  ): void;
159
  addUtilities(
160
    utilities: Record<string, CssInJs | CssInJs[]> | Record<string, CssInJs | CssInJs[]>[],
161
    options?: {}
162
  ): void;
163
  matchUtilities(
164
    utilities: Record<
165
      string,
166
      (value: string, extra: { modifier: string | null }) => CssInJs | CssInJs[]
167
    >,
168
    options?: Partial<{
169
      type: string | string[];
170
      supportsNegativeValues: boolean;
171
      values: Record<string, string>;
172
      modifiers: 'any' | Record<string, string>;
173
    }>
174
  ): void;
175
  addComponents(components: Record<string, CssInJs> | Record<string, CssInJs>[], options?: {}): void;
176
  matchComponents(
177
    components: Record<string, (value: string, extra: { modifier: string | null }) => CssInJs>,
178
    options?: Partial<{
179
      type: string | string[];
180
      supportsNegativeValues: boolean;
181
      values: Record<string, string>;
182
      modifiers: 'any' | Record<string, string>;
183
    }>
184
  ): void;
185
  theme(path: string, defaultValue?: any): any;
186
  config(path?: string, defaultValue?: any): any;
187
  prefix(className: string): string;
188
}
189
```
190

191
[Plugin Development](./plugin-development.md)
192

193
### Theme System
194

195
Comprehensive theme and design system management with CSS custom properties, color palettes, and configuration.
196

197
```typescript { .api }
198
const colors: {
199
  inherit: string;
200
  current: string;
201
  transparent: string;
202
  black: string;
203
  white: string;
204
  slate: Record<string, string>;
205
  gray: Record<string, string>;
206
  // ... all color scales
207
};
208

209
const defaultTheme: {
210
  accentColor: (options: { theme: ThemeFn }) => any;
211
  animation: Record<string, string>;
212
  // ... all theme sections
213
};
214

215
function flattenColorPalette(colors: Colors): Record<string, string>;
216
```
217

218
[Theme System](./theme-system.md)
219

220
### AST Processing
221

222
Low-level CSS abstract syntax tree processing for advanced use cases and custom tooling. Includes utilities for creating, manipulating, and converting AST nodes.
223

224
```typescript { .api }
225
function compileAst(
226
  input: AstNode[],
227
  opts?: CompileOptions
228
): Promise<{
229
  sources: { base: string; pattern: string; negated: boolean }[];
230
  root: Root;
231
  features: Features;
232
  build(candidates: string[]): AstNode[];
233
}>;
234

235
function toCss(ast: AstNode[], withSourceMap?: boolean): string;
236

237
function walk(
238
  ast: AstNode[],
239
  visitor: (node: AstNode, utils: WalkUtils) => void | WalkAction
240
): void;
241

242
function rule(selector: string, nodes: AstNode[]): AtRule | StyleRule;
243
function atRule(name: string, params: string, nodes: AstNode[]): AtRule;
244
function styleRule(selector: string, nodes: AstNode[]): StyleRule;
245
function decl(property: string, value: string): Declaration;
246
function comment(text: string): Comment;
247
function context(ctx: Record<string, any>, nodes: AstNode[]): Context;
248
function atRoot(nodes: AstNode[]): AtRoot;
249
function optimizeAst(ast: AstNode[], designSystem: DesignSystem, polyfills?: Polyfills): AstNode[];
250

251
enum WalkAction {
252
  Continue = 'continue',
253
  Skip = 'skip',
254
  Stop = 'stop',
255
}
256

257
interface WalkUtils {
258
  parent: AstNode | null;
259
  replaceWith: (nodes: AstNode[]) => void;
260
  context: Record<string, any>;
261
}
262
```
263

264
[AST Processing](./ast-processing.md)
265

266
### CSS Assets
267

268
Prebuilt CSS files for different use cases and components of the Tailwind CSS system.
269

270
```typescript { .api }
271
// Main Tailwind CSS file with all components
272
import "tailwindcss/index.css";
273
// or 
274
import "tailwindcss";
275

276
// CSS reset and base styles
277
import "tailwindcss/preflight.css"; 
278
import "tailwindcss/preflight";
279

280
// Theme variable definitions
281
import "tailwindcss/theme.css";
282
import "tailwindcss/theme";
283

284
// Core utility classes
285
import "tailwindcss/utilities.css";
286
import "tailwindcss/utilities";
287
```
288

289
**Asset Files:**
290
- `index.css`: Complete Tailwind CSS framework
291
- `preflight.css`: CSS reset and normalize styles
292
- `theme.css`: Theme variable definitions and custom properties
293
- `utilities.css`: Core utility class definitions
294

295
## Types
296

297
```typescript { .api }
298
type Config = UserConfig;
299

300
enum Polyfills {
301
  None = 0,
302
  AtProperty = 1 << 0,
303
  ColorMix = 1 << 1,
304
  All = AtProperty | ColorMix,
305
}
306

307
enum Features {
308
  None = 0,
309
  AtApply = 1 << 0,
310
  AtImport = 1 << 1,
311
  JsPluginCompat = 1 << 2,
312
  ThemeFunction = 1 << 3,
313
  Utilities = 1 << 4,
314
  Variants = 1 << 5,
315
}
316

317
type Root =
318
  | null
319
  | 'none'
320
  | { base: string; pattern: string };
321

322
type CssInJs = Record<string, string | string[] | CssInJs>;
323

324
type Plugin = PluginFn | PluginWithConfig | PluginWithOptions<any>;
325

326
type PluginFn = (api: PluginAPI) => void;
327

328
interface PluginWithConfig {
329
  handler: PluginFn;
330
  config?: UserConfig;
331
}
332

333
interface PluginWithOptions<T> {
334
  (options?: T): PluginWithConfig;
335
  __isOptionsFunction: true;
336
}
337

338
interface DecodedSourceMap {
339
  version: number;
340
  sources: string[];
341
  sourcesContent: (string | null)[];
342
  names: string[];
343
  mappings: string;
344
  file?: string;
345
  sourceRoot?: string;
346
}
347

348
interface Colors {
349
  [key: string | number]: string | Colors;
350
}
351

352
interface SourceLocation {
353
  start: { line: number; column: number };
354
  end: { line: number; column: number };
355
  source?: string;
356
}
357

358
type AstNode = StyleRule | AtRule | Declaration | Comment | Context | AtRoot;
359

360
interface StyleRule {
361
  kind: 'rule';
362
  selector: string;
363
  nodes: AstNode[];
364
  src?: SourceLocation;
365
  dst?: SourceLocation;
366
}
367

368
interface AtRule {
369
  kind: 'at-rule';
370
  name: string;
371
  params: string;
372
  nodes: AstNode[];
373
  src?: SourceLocation;
374
  dst?: SourceLocation;
375
}
376

377
interface Declaration {
378
  kind: 'declaration';
379
  property: string;
380
  value: string | undefined;
381
  important: boolean;
382
  src?: SourceLocation;
383
  dst?: SourceLocation;
384
}
385

386
interface Comment {
387
  kind: 'comment';
388
  value: string;
389
  src?: SourceLocation;
390
  dst?: SourceLocation;
391
}
392

393
interface Context {
394
  kind: 'context';
395
  context: Record<string, any>;
396
  nodes: AstNode[];
397
}
398

399
interface AtRoot {
400
  kind: 'at-root';
401
  nodes: AstNode[];
402
}
403

404
interface DesignSystem {
405
  theme: any;
406
  invalidCandidates: Set<string>;
407
  important: boolean | null;
408
  variants: any;
409
  parseVariant: (variant: string) => any;
410
}
411
```