Tailwind Config Validator

Validate JSON-exported Tailwind CSS configuration files for structural issues, content path problems, theme misconfiguration, and best practices. Use when au...

Security Scan

The skill's files, runtime instructions, and requested resources are consistent with a local Tailwind config linter; nothing in the package indicates hidden network exfiltration or unrelated privileges, but exercise normal caution when executing project JS to produce the JSON input.

Purpose & Capability

Name/description match the provided code and instructions. The tool only needs a JSON-exported Tailwind config and the included Python validator operates on that JSON; there are no unrelated environment variables, credentials, or binaries declared.

Instruction Scope

SKILL.md tells the user to run node -e "console.log(JSON.stringify(require('./tailwind.config.js')))" which will execute the project's tailwind.config.js to produce JSON. Executing project JS is required to export the config but can run arbitrary code in that file — the validator itself appears to only read local JSON and perform static checks. Recommend only exporting configs from trusted repositories or running the node export in an isolated environment.

Install Mechanism

No install spec (instruction-only with an included script). No downloads or external package installs are requested; the SKILL.md and script state pure Python stdlib usage.

Credentials

The skill requests no environment variables, no credentials, and no config paths. The declared requirements are proportional to a local static validator.

Persistence & Privilege

Skill is not always-enabled and uses normal model invocation settings. It does not request system-wide configuration or persistent privileges.

Assessment

This skill appears to be a straightforward local validator for JSON-exported Tailwind configs and does not require credentials or external installs. Before running it: (1) Inspect the included script (scripts/tailwind_config_validator.py) yourself to confirm it matches expectations — it appears to use only Python stdlib and local file reads. (2) Be careful when running the suggested node command to export the config: require('./tailwind.config.js') will execute that JS/TS file, which may contain arbitrary code from the project. Only run the node export on code you trust or run it inside a sandbox/container. (3) If you want extra assurance, run node -e on a copy of the config file or convert the config to JSON by hand, then run the validator. If you want me to, I can scan the full Python script for network/socket/subprocess usage or search for os.environ accesses and report back.

Validate Tailwind CSS configuration files exported as JSON for structural correctness, content path issues, theme misconfiguration, dark mode problems, plugin hygiene, and best practices. Pure Python 3 stdlib — no external dependencies.

Note: Tailwind configs are JS/TS, not directly parseable. This validator works with JSON-exported configs. Export via:

node -e "console.log(JSON.stringify(require('./tailwind.config.js')))" > config.json
python3 scripts/tailwind_config_validator.py validate config.json

Commands

validate — Full validation with all rules

python3 scripts/tailwind_config_validator.py validate config.json
python3 scripts/tailwind_config_validator.py validate config.json --strict
python3 scripts/tailwind_config_validator.py validate config.json --format json

lint — Run all rules (alias for validate)

python3 scripts/tailwind_config_validator.py lint config.json
python3 scripts/tailwind_config_validator.py lint config.json --format summary
python3 scripts/tailwind_config_validator.py lint config.json --strict --format json

content — Check content configuration

python3 scripts/tailwind_config_validator.py content config.json
python3 scripts/tailwind_config_validator.py content config.json --format json
python3 scripts/tailwind_config_validator.py content config.json --format summary

theme — Check theme configuration

python3 scripts/tailwind_config_validator.py theme config.json
python3 scripts/tailwind_config_validator.py theme config.json --format json
python3 scripts/tailwind_config_validator.py theme config.json --format summary

Flags

Flag	Description
--strict	Treat warnings as errors — exit code 1 (CI-friendly)
--format text	Human-readable output (default)
--format json	Machine-readable JSON
--format summary	Compact summary with counts

Validation Rules (26)

Structure (5)

Rule	Severity	Description
S1	error	File not found or unreadable
S2	error	Empty config file
S3	error	Invalid JSON syntax
S4	warning/info	Unknown top-level keys (valid: content, theme, plugins, presets, darkMode, prefix, important, separator, corePlugins, safelist, blocklist, future, experimental)
S5	info	JS/TS config detected (hint to export as JSON)

Content (5)

Rule	Severity	Description
C1	error	Missing content paths (required for tree-shaking)
C2	warning	Empty content array
C3	warning	Content paths include node_modules (performance)
C4	warning	Content glob too broad (e.g. **/* without extension filter)
C5	info	Suspicious content pattern (bare *.css or similar)

Theme (5)

Rule	Severity	Description
T1	warning	Overriding entire theme key without extend (replaces defaults)
T2	info	Empty theme.extend object
T3	warning	Invalid color values (not strings)
T4	info	Referencing default theme without callback (theme() needed)
T5	warning	Custom screen breakpoints not in ascending order

Dark Mode (2)

Rule	Severity	Description
D1	error	Invalid darkMode value
D2	info	darkMode "class" deprecated in v3.4+ (use "selector")

Plugins (3)

Rule	Severity	Description
P1	info	Empty plugins array
P2	error	Plugins not an array
P3	info	Deprecated official plugins (built-in in v4)

Best Practices (6)

Rule	Severity	Description
B1	error	No content paths defined (tree-shaking broken)
B2	warning	Using important: true globally (anti-pattern)
B3	warning	Prefix with special characters
B4	warning	corePlugins disabled entirely
B5	warning	Large safelist (>50 patterns, bloats CSS)
B6	warning	Missing theme.extend (all customizations override defaults)

Exit Codes

Code	Meaning
0	No errors (warnings allowed unless --strict)
1	Errors found (or warnings in --strict mode)
2	File not found / parse error

CI Integration

# GitHub Actions example
- name: Validate Tailwind config
  run: |
    node -e "console.log(JSON.stringify(require('./tailwind.config.js')))" > /tmp/tw-config.json
    python3 scripts/tailwind_config_validator.py validate /tmp/tw-config.json --strict --format json

Example Output

tailwind.config validate — config.json
=======================================
[ERROR  ] C1: Missing 'content' paths — required for tree-shaking
         Without content paths, Tailwind cannot purge unused CSS. Add content: ['./src/**/*.{html,js,ts,jsx,tsx}'].
[WARNING] T1: theme.colors overrides all default colors — use theme.extend.colors instead
         Placing keys directly under 'theme' replaces the entire default set. Move to 'theme.extend' to merge with defaults.
[WARNING] B2: important: true applies !important to all utilities (anti-pattern)
         Prefer important: '#app' to scope specificity to a root selector instead of global !important.
[INFO   ] P3: Plugin '@tailwindcss/forms' is built-in since Tailwind v4
         In Tailwind v4, @tailwindcss/forms functionality is included by default. Remove the plugin if upgrading.
[INFO   ] D2: darkMode 'class' is deprecated since v3.4 — use 'selector' instead
         The 'class' strategy still works but 'selector' is the recommended replacement.

Result: INVALID
Summary: 1 error(s), 2 warning(s), 2 info