tailwind-4-docs

Status: Not initialized
Source: https://github.com/tailwindlabs/tailwindcss.com
Docs-Path: src/docs
Index-Path: src/app/(docs)/docs/index.tsx
Snapshot-Date: (none)
Note: Run skills/tailwind-4-docs/scripts/sync_tailwind_docs.py --accept-docs-license to initialize.

# Tailwind Engineering Playbook

Use this reference for implementation, refactor, and review tasks where you need practical engineering judgment in addition to the official Tailwind docs. Its purpose is to help you make good architectural decisions quickly when you are writing, reviewing or refactoring Tailwind code.

## Default workflow

1. Inspect the repo first.
2. Find the Tailwind entrypoint CSS and any split files.
3. Identify existing theme tokens, breakpoints, component classes, custom utilities, and formatting conventions.
4. Prefer using the project's existing design language over inventing a new one.
5. Keep the implementation as close to markup as possible.
6. Only add new abstraction when repetition or lack of a design primitive actually justifies it.

## Core mindset

- The default move is to compose UI in markup with utilities.
- Custom CSS is still valuable for tokens, utilities, component classes, rich text, and third-party markup.

## The abstraction ladder

Use this order by default:

1. Compose with existing utilities in markup.
2. If markup repeats, extract the markup into the project's native reusable abstraction, such as a component, partial, include, or template.
3. If repeated values are missing from the system, add tokens with `@theme`.
4. If a repeated low-level behavior is missing, add a custom utility with `@utility`.
5. If a stable named visual primitive is justified, add a small component class in `@layer components`.
6. Use `@apply` only as a narrow adapter, not as the main architecture.

## What good reuse looks like

The first level of reuse is the Tailwind design system itself:

- spacing scale
- color system
- type scale
- radius scale
- shadow scale
- breakpoint scale
- container behavior

The second level of reuse is markup reuse:

- shared cards
- buttons
- hero sections
- CTA blocks
- pagination items
- list items
- nav items

The third level of reuse is CSS abstraction:

- tokens
- custom utilities
- custom variants
- small component classes

## Tokens first

Create a token when a value is part of the design language and should be reusable:

- brand colors
- semantic surface or text colors
- typography scale
- font families
- radii
- shadows
- spacing decisions that should be global
- container widths
- breakpoints

Do not create tokens for one-off values too early.

Use an arbitrary value first when the value:

- is a real exception
- appears only once
- is unlikely to become part of the system

Promote it into a token when:

- it appears repeatedly
- it has product meaning
- design wants it governed centrally
- a later redesign should update all usages together

Prefer semantic token names where semantics matter, especially for colors:

- `--color-primary`
- `--color-surface-muted`
- `--color-danger`

Use `@theme` when the token should generate utilities or variants.
Use `:root` only for regular CSS variables that are not supposed to create utility classes.

## Arbitrary values

Use them for:

- one-off alignment or layout tuning
- design details that are not system-level
- third-party or generated markup constraints

Do not let repeated arbitrary values accumulate. If the same value shows up several times, it is usually time for a token or a custom utility.

## Custom utilities

Use `@utility` when you need a low-level reusable behavior that Tailwind does not already provide.

Good candidates:

- a project container helper
- a focus-ring preset
- a custom text wrap helper
- a low-level layout helper
- a transition preset

A custom utility should still feel like a utility:

- one job
- low level
- composable
- not semantic

## Component classes

Create component classes only for stable, intentional APIs:

- `btn`
- `card`
- `badge`
- `field-input`
- `callout`
- `rich-text`

They are also appropriate when you need to style markup you don't control:

- CMS-rendered content
- third-party widgets
- generated framework markup

Do not create component classes just to hide utilities from templates.

Good component classes are:

- small
- stable
- easy to override
- tied to real repeated primitives

Bad component classes are:

- page-specific
- giant
- bundles of unrelated concerns
- substitutes for component extraction

## Variant strategy for component classes

When a component has likely variants, keep the base class neutral where possible.

Example of good separation:

- base class owns layout, spacing, and shared behavior
- separate variant classes own tone or intent
- size variants are separate classes

This avoids a common problem where the base component class hardcodes colors or state behavior, then every exception has to fight the CSS.

If you create a shared component abstraction, it should own its shared behavior consistently:

- hover transitions
- focus treatment
- icon motion
- spacing between label and icon
- disabled or active states

Do not leave half the behavior in the abstraction and the other half duplicated ad hoc in templates.

## `@apply`

Use `@apply` sparingly.

Good uses:

- styling third-party classes you don't control
- adapting Tailwind styles to generated markup
- tiny repeated patterns where markup extraction would be worse

Bad uses:

- hiding all utilities in CSS
- creating giant semantic wrappers that are harder to reason about than the original markup

If you are using `@apply` heavily to shorten templates, step back and reconsider the abstraction ladder.

## Custom variants

Use `@custom-variant` when a selector pattern is truly repeated and deserves to become a styling primitive.

Good candidates:

- app theme wrappers
- data-attribute driven states
- repeated container context selectors
- CMS-specific context wrappers (e.g. dark page section, highlighted block)

Do not create custom variants for one-off selector tricks unless the repetition is real.

## Rich text and uncontrolled markup

Rich text is a special case because you usually do not control the inner HTML.

Use one of these approaches:

- a scoped wrapper such as `.rich-text`
- the official Typography plugin

Do not globally style every `h1`, `p`, `ul`, or `table` in the whole app just to fix one content region.

Scope the styling to the content container.

## Generated DOM and JS-replaced markup

When styling icons or widgets that are transformed by JavaScript, target the rendered DOM, not only the placeholder markup.

Examples:

- icon libraries that replace `<i>` with `<svg>`
- component libraries that inject wrappers
- widgets that rewrite class names or structure

If a shared interaction depends on a specific child element, verify that the final rendered DOM still matches the selector.

This matters a lot for:

- transitions
- hover effects
- focus styles
- icon animation
- nested selectors in component classes

## Responsive strategy

Prefer mobile-first styling:

- define the base case first
- add larger breakpoint changes progressively

Use breakpoint tokens intentionally. In v4, `--breakpoint-*` theme variables define which responsive variants exist.

Do not blindly use every default breakpoint if the project intentionally removed or replaced some of them.

## File organization

For a CSS-first Tailwind v4 setup, this structure is usually sensible:

- entrypoint CSS (`app.css` or `site.css`)
- `theme.css` for tokens
- `base.css` for minimal element defaults
- `utilities.css` for low-level project utilities and variants
- `components.css` for a small stable component API
  - Bigger components, e.g. `rich-text.css` for scoped uncontrolled HTML

## Refactor heuristics

When refactoring an existing Tailwind codebase:

1. Remove dead CSS before adding new CSS.
2. Remove redundant utilities before extracting abstractions.
3. Normalize obvious repeated primitives first.
4. Keep the number of component classes intentionally small.
5. Push page structure back into markup if CSS started owning too much layout.
6. Merge inconsistent implementations of the same affordance.

Watch for these smells:

- several versions of the same button or card
- repeated arbitrary shadows, radii, or spacing
- identical hover interactions implemented in different ways
- state logic split between a shared class and page-specific one-offs
- component classes that are really page fragments in disguise

## Review checklist

Before finalizing a Tailwind change, check:

- Are utilities sufficient here, or did I abstract too early?
- If repetition exists, would extracting markup be better than adding CSS?
- Should repeated values become tokens?
- Are custom utilities truly low-level?
- Are component classes small, stable, and override-friendly?
- Are state and motion rules consistent across similar UI?
- Will Tailwind detect every class I used?
- Are dynamic classes mapped to full strings?
- Is uncontrolled markup scoped instead of styled globally?
- Is the responsive behavior mobile-first and intentional?
- Can any CSS be deleted now?

## Practical defaults

When in doubt:

- keep styling in markup first
- reuse markup before reusing CSS
- use tokens before arbitrary repetition
- use custom utilities before semantic CSS wrappers
- keep component classes few and durable
- keep state behavior inside the shared abstraction if the abstraction exists
- verify that rendered DOM matches your selectors
- prefer deleting complexity over introducing a clever abstraction

# Tailwind CSS v4 gotchas (quick scan)

- Browser support is modern-only: Safari 16.4+, Chrome 111+, Firefox 128+.
- PostCSS plugin moved to `@tailwindcss/postcss`.
- CLI moved to `@tailwindcss/cli`.
- Vite plugin `@tailwindcss/vite` is recommended.
- Import Tailwind with `@import "tailwindcss";` (no `@tailwind` directives).
- Prefix syntax is `@import "tailwindcss" prefix(tw);` and classes use `tw:` at the start.
- Important modifier goes at the end: `bg-red-500!`.
- Utility renames and removals: see `references/docs/upgrade-guide.mdx` for the full list.
- Default border and ring color now use `currentColor`; ring width default is 1px.
- `space-*` and `divide-*` selectors changed; use flex/grid with `gap` if layouts break.
- Custom utilities should use `@utility` instead of `@layer utilities` or `@layer components`.
- `@theme` is for design tokens that should create utilities or variants; use `:root` only for plain CSS variables that should not generate Tailwind APIs.
- `@theme` variables must be top-level, not nested under selectors or media queries.
- Stacked variants apply left-to-right (reverse order from v3).
- Arbitrary CSS variable syntax is `bg-(--brand-color)` (not `bg-[--brand-color]`).
- Transform reset uses `scale-none`, `rotate-none`, `translate-none` (not `transform-none`).
- `hover:` now only applies on devices that support hover; override if needed.
- Tailwind scans source files as plain text, so dynamically concatenated class fragments are not detected.
- Use `@source` for external or unusual source locations, and `@source inline()` only when safelisting is truly necessary.
- CSS modules and component `<style>` blocks need `@reference` to access theme vars.

#!/usr/bin/env python
"""Sync Tailwind CSS docs snapshot into this skill.

Clones the tailwindcss.com repo (or uses an existing local clone) and copies
`src/docs` plus the docs index into references.
"""

from __future__ import annotations

import argparse
import datetime as dt
import shutil
import subprocess
import tempfile
from pathlib import Path

DEFAULT_REPO_URL = "https://github.com/tailwindlabs/tailwindcss.com"
DEFAULT_REF = "main"
LICENSE_URL = "https://github.com/tailwindlabs/tailwindcss.com#license"


def run(cmd: list[str], cwd: Path | None = None) -> str:
    result = subprocess.run(cmd, cwd=cwd, check=True, capture_output=True, text=True)
    return result.stdout.strip()


def clone_repo(repo_url: str, ref: str, dest: Path) -> None:
    run(["git", "clone", "--depth", "1", "--branch", ref, repo_url, str(dest)])


def update_repo(repo_dir: Path, ref: str) -> None:
    run(["git", "fetch", "--depth", "1", "origin", ref], cwd=repo_dir)
    run(["git", "checkout", ref], cwd=repo_dir)
    run(["git", "reset", "--hard", f"origin/{ref}"], cwd=repo_dir)


def write_source_file(
    path: Path,
    repo_url: str,
    commit: str,
    commit_date: str,
    snapshot_date: str,
) -> None:
    content = "\n".join(
        [
            f"Source: {repo_url}",
            f"Commit: {commit}",
            f"Commit-Date: {commit_date}",
            "Docs-Path: src/docs",
            "Index-Path: src/app/(docs)/docs/index.tsx",
            f"Snapshot-Date: {snapshot_date}",
            "",
        ]
    )
    path.write_text(content, encoding="utf-8")


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("--repo-url", default=DEFAULT_REPO_URL)
    parser.add_argument("--ref", default=DEFAULT_REF)
    parser.add_argument(
        "--local-repo",
        default=None,
        help="Use an existing local repo clone instead of cloning a temp copy.",
    )
    parser.add_argument(
        "--accept-docs-license",
        action="store_true",
        help="Acknowledge the Tailwind docs license before downloading.",
    )
    args = parser.parse_args()

    if not args.accept_docs_license:
        raise SystemExit(
            "This script downloads docs from tailwindcss.com, which is source-available "
            "but not open-source. Review the license and re-run with "
            f"--accept-docs-license. License: {LICENSE_URL}"
        )

    skill_root = Path(__file__).resolve().parents[1]
    references_dir = skill_root / "references"
    docs_dir = references_dir / "docs"
    index_out = references_dir / "docs-index.tsx"
    source_out = references_dir / "docs-source.txt"

    if args.local_repo:
        repo_dir = Path(args.local_repo).resolve()
        if not repo_dir.exists():
            raise SystemExit(f"Local repo not found: {repo_dir}")
        update_repo(repo_dir, args.ref)
        cleanup = None
    else:
        temp_dir = tempfile.TemporaryDirectory()
        repo_dir = Path(temp_dir.name)
        clone_repo(args.repo_url, args.ref, repo_dir)
        cleanup = temp_dir

    try:
        docs_src = repo_dir / "src" / "docs"
        index_src = repo_dir / "src" / "app" / "(docs)" / "docs" / "index.tsx"

        if not docs_src.exists():
            raise SystemExit(f"Docs folder not found: {docs_src}")
        if not index_src.exists():
            raise SystemExit(f"Docs index not found: {index_src}")

        if docs_dir.exists():
            shutil.rmtree(docs_dir)
        docs_dir.mkdir(parents=True, exist_ok=True)
        shutil.copytree(docs_src, docs_dir, dirs_exist_ok=True)
        shutil.copy2(index_src, index_out)

        commit = run(["git", "rev-parse", "HEAD"], cwd=repo_dir)
        commit_date = run(["git", "log", "-1", "--format=%ci"], cwd=repo_dir)
        snapshot_date = dt.date.today().isoformat()
        write_source_file(source_out, args.repo_url, commit, commit_date, snapshot_date)
    finally:
        if cleanup is not None:
            cleanup.cleanup()


if __name__ == "__main__":
    main()

---
name: tailwind-4-docs
description: Comprehensive Tailwind CSS v4 documentation snapshot and workflow guidance. Use when answering Tailwind v4 questions, selecting utilities/variants, configuring Tailwind v4, or migrating projects from v3 to v4 with official docs and gotcha checks.
compatibility: Requires git, Python 3, and internet access to initialize the Tailwind docs snapshot from tailwindcss.com.
---

# Tailwind 4 Docs

## Overview

Use this skill to navigate a locally synced Tailwind CSS v4 documentation snapshot and answer development, configuration, migration, implementation, refactor, and review questions with official guidance.

The docs snapshot is not bundled with this skill because the upstream repository is source-available but not open-source. Users must initialize the snapshot themselves and are responsible for complying with the upstream license.

## Quick start

1. Check whether the docs snapshot is initialized (`references/docs/` and `references/docs-index.tsx` exist).
2. If the snapshot is missing or older than one week, stop and ask to run the initialization step in "Initialization" before continuing. Do not answer the user's question until the snapshot is initialized.
3. Identify the topic (utility, variant, config, migration, compatibility, implementation, refactor, review).
4. Find the matching doc in `references/docs-index.tsx`.
5. Load only the relevant file from `references/docs/`.
6. For implementation, refactor, or review tasks, also load `references/engineering-playbook.md`.
7. Apply guidance and call out any breaking changes or constraints.

## Initialization (required once per install)

Run the sync script to download the Tailwind docs locally. This requires network access, git, and Python 3:

```
python skills/tailwind-4-docs/scripts/sync_tailwind_docs.py --accept-docs-license
```

This pulls content from `tailwindlabs/tailwindcss.com`. That repo is source-available and explicitly not open-source, so the user must accept its license before downloading and keep the snapshot local.

If you cannot run tools or have no internet access, ask the user to run the exact command above in a terminal, then continue once `references/docs/` and `references/docs-index.tsx` exist.

If the snapshot is missing or older than one week, you must ask for permission to run the command or ask the user to run it. Do not proceed with Tailwind guidance until the snapshot is initialized or refreshed.

If initialization is blocked (no internet or no write access), use `references/gotchas.md` as a limited fallback and ask the user to consult the official docs. For implementation, refactor, or review tasks, `references/engineering-playbook.md` can also serve as a limited fallback.

## References map

- `references/docs/` is generated locally and contains the Tailwind v4 MDX docs snapshot.
- `references/docs-index.tsx` is generated locally and contains the category and slug map used by the docs sidebar.
- `references/docs-source.txt` captures the upstream repo, commit, and snapshot date (or reports that initialization is pending).
- `references/engineering-playbook.md` is the agent-oriented implementation, refactor, and review guide.
- `references/gotchas.md` provides a quick scan of common v4 migration pitfalls.

## MDX handling

- Treat `export const title` and `export const description` as metadata.
- Read JSX callouts like `<TipInfo>` or `<TipBad>` as guidance text.

## Common entry points

- Migration: `references/docs/upgrade-guide.mdx`, `references/docs/compatibility.mdx`.
- Implementation/refactor/review: `references/engineering-playbook.md`.
- Gotchas overview: `references/gotchas.md`.
- Configuration and directives: `references/docs/functions-and-directives.mdx`, `references/docs/adding-custom-styles.mdx`, `references/docs/theme.mdx`.
- Variants and responsive patterns: `references/docs/hover-focus-and-other-states.mdx`, `references/docs/responsive-design.mdx`.
- Core behavior: `references/docs/preflight.mdx`, `references/docs/detecting-classes-in-source-files.mdx`.

## Migration checklist

When upgrading from v3 to v4, always confirm the following in the docs:

- Browser support and compatibility expectations.
- Tooling changes: `@tailwindcss/postcss`, `@tailwindcss/cli`, `@tailwindcss/vite`.
- Import syntax: `@import "tailwindcss"` replaces `@tailwind` directives.
- Utility renames/removals, prefix format, and important modifier placement.
- Changes to variants, transforms, and arbitrary value syntax.

## Update workflow

Run `scripts/sync_tailwind_docs.py` to refresh the snapshot. Use `--local-repo` if you already have a local clone of `tailwindlabs/tailwindcss.com` to speed up syncs. Always pass `--accept-docs-license`.

---