Tailwind CSS v4 skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Tailwind CSS v4"
  short_description: "Config in CSS, upgrade without visual drift"
  default_prompt: "$tailwind-v4 Upgrade this project from Tailwind 3 to Tailwind 4 and check nothing looks different"

#!/usr/bin/env python3
"""Find Tailwind CSS v3-only classes and directives in a source tree.

Two modes:
  default      Report things that do not exist in Tailwind v4 at all (opacity
               utilities, flex-shrink/grow, overflow-ellipsis, @tailwind
               directives, bracketed CSS-variable shorthand). Safe to run after
               an upgrade: every hit is a real leftover.
  --inventory  Also report v3 classes whose meaning changed in v4 (shadow-sm,
               rounded, bare ring, outline-none, ...). Run this BEFORE upgrading
               to size the work; after upgrading these names are valid v4
               classes with different values, so hits are expected.

Usage:
  python3 scan_v3_classes.py [--inventory] [--json] <dir-or-file> [...]

Exit code: 0 when nothing is found, 1 when findings exist, 2 on bad usage.
Standard library only.
"""
from __future__ import annotations

import json
import os
import re
import sys

CODE_EXT = {".html", ".htm", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".vue",
            ".svelte", ".astro", ".mdx", ".md", ".php", ".erb", ".twig", ".liquid",
            ".hbs", ".njk", ".cshtml", ".razor", ".py", ".rb", ".ex", ".heex"}
CSS_EXT = {".css", ".scss", ".pcss", ".postcss", ".less"}
SKIP_DIRS = {"node_modules", ".git", "dist", "build", ".next", ".nuxt", ".output",
             ".svelte-kit", ".astro", "coverage", "vendor", ".turbo", ".cache"}

# Removed in v4 (any hit is a leftover). (regex on the bare utility, suggestion)
REMOVED = [
    (re.compile(r"^(bg|text|border|divide|ring|placeholder)-opacity-\d+$"),
     "use an opacity modifier on the color, e.g. bg-black/50"),
    (re.compile(r"^flex-shrink(-\d+)?$"), "use shrink / shrink-0"),
    (re.compile(r"^flex-grow(-\d+)?$"), "use grow / grow-0"),
    (re.compile(r"^overflow-ellipsis$"), "use text-ellipsis"),
    (re.compile(r"^decoration-(slice|clone)$"), "use box-decoration-slice / box-decoration-clone"),
    (re.compile(r"^[a-z-]+-\[--[A-Za-z0-9_-]+\]$"), "v4 shorthand for CSS variables is parentheses: bg-(--brand)"),
]

# Renamed or changed meaning between v3 and v4 (inventory mode only).
RENAMED = {
    "shadow-sm": "shadow-xs", "shadow": "shadow-sm",
    "drop-shadow-sm": "drop-shadow-xs", "drop-shadow": "drop-shadow-sm",
    "blur-sm": "blur-xs", "blur": "blur-sm",
    "backdrop-blur-sm": "backdrop-blur-xs", "backdrop-blur": "backdrop-blur-sm",
    "rounded-sm": "rounded-xs", "rounded": "rounded-sm",
    "outline-none": "outline-hidden",
    "ring": "ring-3 (v4 bare ring is 1px, currentColor)",
}
BEHAVIOUR = {
    "border": "default border color is currentColor in v4; add a color (border-gray-200)",
    "divide-x": "default divide color is currentColor in v4; add a color",
    "divide-y": "default divide color is currentColor in v4; add a color",
}
BARE_AMBIGUOUS = {"shadow", "rounded", "ring", "blur", "border", "drop-shadow", "backdrop-blur"}

CSS_RULES = [
    (re.compile(r"@tailwind\s+(base|components|utilities)"), 'replace with @import "tailwindcss";'),
    (re.compile(r"\btheme\([^)]*\)"), "prefer var(--color-...) / var(--spacing) theme variables"),
    (re.compile(r"@layer\s+utilities\s*\{"), "custom utilities become @utility name { ... } in v4"),
    (re.compile(r"@layer\s+components\s*\{"), "v4: keep for component classes, or convert to @utility for variant support"),
]

STRING_RE = re.compile(r"\"([^\"\n]*)\"|'([^'\n]*)'|`([^`]*)`")
TW_HINT = re.compile(
    r"^-?(p[xytrbl]?|m[xytrbl]?|w|h|size|min-w|max-w|min-h|max-h|flex|grid|gap|text|bg|"
    r"font|leading|tracking|items|justify|self|place|inset|top|left|right|bottom|z|"
    r"opacity|transition|duration|ease|space-[xy]|divide|overflow|cursor|col|row|"
    r"order|basis|aspect|object|shadow|rounded|ring|border|outline|blur|hidden|block|"
    r"inline|absolute|relative|fixed|sticky|truncate|underline|uppercase|sr-only)\b")


def bare(token: str) -> str:
    """Strip variants (hover:, md:, [&>*]:) and important markers from a class token."""
    depth, cut = 0, -1
    for i, ch in enumerate(token):
        if ch == "[":
            depth += 1
        elif ch == "]":
            depth -= 1
        elif ch == ":" and depth == 0:
            cut = i
    t = token[cut + 1:]
    return t.strip("!")


def classify(token: str, inventory: bool, string_is_classes: bool):
    t = bare(token)
    for rx, hint in REMOVED:
        if rx.match(t):
            return ("removed", hint)
    if not inventory:
        return None
    if t in BARE_AMBIGUOUS and not string_is_classes:
        return None
    if t in RENAMED:
        return ("renamed", f"v3 {t} -> v4 {RENAMED[t]}")
    if t in BEHAVIOUR:
        return ("behaviour", BEHAVIOUR[t])
    if token.startswith("!") and len(token) > 1:
        return ("syntax", f"important modifier goes at the end in v4: {token[1:]}!")
    return None


def scan_code(path: str, inventory: bool, out: list):
    with open(path, encoding="utf-8", errors="replace") as fh:
        for lineno, line in enumerate(fh, 1):
            for m in STRING_RE.finditer(line):
                s = next(g for g in m.groups() if g is not None)
                tokens = s.split()
                if not tokens:
                    continue
                twish = sum(1 for tk in tokens if TW_HINT.match(bare(tk)))
                is_classes = len(tokens) >= 2 and twish >= 2
                for tk in tokens:
                    hit = classify(tk, inventory, is_classes)
                    if hit:
                        out.append({"file": path, "line": lineno, "token": tk, "kind": hit[0], "hint": hit[1]})


def scan_css(path: str, inventory: bool, out: list):
    with open(path, encoding="utf-8", errors="replace") as fh:
        for lineno, line in enumerate(fh, 1):
            for rx, hint in CSS_RULES:
                if rx.search(line):
                    out.append({"file": path, "line": lineno, "token": rx.search(line).group(0),
                                "kind": "css", "hint": hint})
            m = re.search(r"@apply\s+([^;]+);", line)
            if m:
                for tk in m.group(1).split():
                    hit = classify(tk, inventory, True)
                    if hit:
                        out.append({"file": path, "line": lineno, "token": tk, "kind": hit[0], "hint": hit[1]})


def walk(target: str):
    if os.path.isfile(target):
        yield target
        return
    for root, dirs, files in os.walk(target):
        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
        for f in files:
            yield os.path.join(root, f)


def main(argv: list[str]) -> int:
    inventory = "--inventory" in argv
    as_json = "--json" in argv
    targets = [a for a in argv if not a.startswith("--")]
    if not targets:
        print(__doc__.strip(), file=sys.stderr)
        return 2
    findings: list = []
    files = 0
    for t in targets:
        if not os.path.exists(t):
            print(f"error: {t} does not exist", file=sys.stderr)
            return 2
        for p in walk(t):
            ext = os.path.splitext(p)[1].lower()
            if ext in CSS_EXT:
                files += 1
                scan_css(p, inventory, findings)
            elif ext in CODE_EXT:
                files += 1
                scan_code(p, inventory, findings)
    if as_json:
        print(json.dumps({"files_scanned": files, "findings": findings}, indent=2))
    else:
        for f in findings:
            print(f"{f['file']}:{f['line']}: [{f['kind']}] {f['token']} -> {f['hint']}")
        kinds: dict = {}
        for f in findings:
            kinds[f["kind"]] = kinds.get(f["kind"], 0) + 1
        summary = ", ".join(f"{k}={v}" for k, v in sorted(kinds.items())) or "none"
        mode = "inventory" if inventory else "leftovers"
        print(f"\nScanned {files} files ({mode} mode). Findings: {len(findings)} ({summary})")
    return 1 if findings else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))