File and Folder Organization

As Tailwind projects grow, the number of files involving CSS-related configuration — the Tailwind config, PostCSS config, global stylesheets, and component-level CSS — multiplies. Without a clear structure, these files scatter across the project and become hard to find. Good file organization makes it immediately obvious where to add new values, where global overrides live, and which CSS belongs to which component.

Config files that affect the entire build — tailwind.config.js, postcss.config.js, and .prettierrc — live at the project root alongside package.json. They are root-level because build tools discover them by convention. Never nest them inside src/ unless your toolchain explicitly supports non-root config discovery.

Place all CSS files inside a dedicated src/styles/ directory. The main entry point is globals.css, which contains the three @tailwind directives, @layer overrides for base elements, and imports for any additional stylesheets. Component-specific CSS goes in separate files like button.css or prose-overrides.css, imported into globals.css.

The globals.css file is the entry point imported into your application's root. It declares the three Tailwind directives in order, then imports any additional stylesheets. Avoid putting custom styles directly in this file beyond the directives — keep custom layer declarations in their own files that are imported here for clarity.

For component-based frameworks like React or Vue, you can co-locate a small CSS file alongside the component file when the styles are tightly coupled. However, in Tailwind projects this is rare since most styling lives in class names directly in the markup. Reserve co-located CSS only for styles that genuinely cannot be expressed with utilities — such as complex :focus-within selectors or @keyframes.

When the tailwind.config.js grows large, extract the theme.extend object into a separate file like theme/extend.js. This keeps the root config file short and readable, while the theme extension file can grow as long as needed. Import and spread the extension back in the main config.

If your project uses several Tailwind plugins and each requires significant configuration, extract plugin setups into their own files inside a plugins/ directory. Each file exports a configured plugin and is imported in the main config's plugins array. This makes it easy to see which plugins are active and to adjust their settings independently.

Design tokens — colors, typography, spacing — are best defined in a separate tokens/ directory rather than inline in the Tailwind config. Each category of tokens lives in its own file: tokens/colors.js, tokens/typography.js, tokens/spacing.js. These files can be shared with design tools, Storybook configurations, and the Tailwind config simultaneously.

Keep content glob patterns organized and readable. Group them by file type and location rather than writing one catch-all glob that scans too broadly. Comment each glob to explain which part of the project it covers. Maintain this list actively — remove old patterns when directories are renamed or removed, and add new patterns when new file types are introduced.

When using @layer to add custom styles, follow a consistent naming approach. Use @layer base for element-level resets (e.g., a, h1, input), @layer components for multi-utility patterns with meaningful names (.btn, .card), and @layer utilities for single-purpose utilities not in Tailwind's default set. Never mix these responsibilities.

Document the file and folder structure in your project's README or a dedicated STYLE_GUIDE.md. Include a diagram of the src/styles/ directory, explain which file each kind of style goes in, and note the content glob maintenance responsibility. New developers should be able to understand where to add a new custom color or a new component class by reading a single page of documentation.

Test your understanding of Tailwind CSS Mastery concepts from this lesson.

In this lesson you learned: keeping config files at the project root for toolchain compatibility, organizing styles into a src/styles/ directory with separate files per layer, and extracting theme tokens and plugins into dedicated files as the config grows. Next up we explore coexisting with legacy CSS in existing projects.