Postcss Config Validator

SKILL.md

---
name: postcss-config-validator
description: Validate PostCSS config files (.postcssrc, postcss.config.js, package.json#postcss) for plugin ordering, deprecated plugins, Tailwind integration, and best practices. Use when validating CSS processing configs, auditing PostCSS setups, or linting frontend build configuration.
---

# PostCSS Config Validator

Validate `.postcssrc`, `.postcssrc.json`, `postcss.config.js`, `postcss.config.ts`, and `package.json#postcss` for deprecated plugins, ordering issues, Tailwind integration problems, parser misconfiguration, and best practices. JS/TS configs are detected but cannot be statically validated. Supports text, JSON, and summary output formats with CI-friendly exit codes.

## Commands

```bash
# Full validation (all 22+ rules)
python3 scripts/postcss_config_validator.py validate .postcssrc

# Quick structure-only check
python3 scripts/postcss_config_validator.py check .postcssrc.json

# Explain config in human-readable form
python3 scripts/postcss_config_validator.py explain package.json

# Suggest improvements
python3 scripts/postcss_config_validator.py suggest .postcssrc

# JSON output (CI-friendly)
python3 scripts/postcss_config_validator.py validate .postcssrc --format json

# Summary only (pass/fail + counts)
python3 scripts/postcss_config_validator.py validate .postcssrc --format summary

# Strict mode (warnings and infos become errors)
python3 scripts/postcss_config_validator.py validate .postcssrc --strict
```

## Rules (22+)

| # | ID | Category | Severity | Rule |
|---|-----|----------|----------|------|
| 1 | S1 | Structure | Error | File not found or unreadable |
| 2 | S2 | Structure | Error | Empty config file |
| 3 | S3 | Structure | Error | Invalid JSON syntax |
| 4 | S4 | Structure | Warning | Unknown top-level keys (valid: plugins, parser, syntax, stringifier, map, from, to) |
| 5 | S5 | Structure | Info | JS/TS config detected — cannot statically validate |
| 6 | P1 | Plugins | Warning | Empty plugins object/array |
| 7 | P2 | Plugins | Warning | Deprecated plugin (autoprefixer-core, postcss-cssnext, lost, postcss-sprites) |
| 8 | P3 | Plugins | Warning | Duplicate plugins |
| 9 | P4 | Plugins | Info | Plugin ordering issues (autoprefixer after preset-env, cssnano last) |
| 10 | P5 | Plugins | Info | postcss-import should be first plugin |
| 11 | P6 | Plugins | Info | Unknown/uncommon plugin name (not in top 50 list) |
| 12 | T1 | Tailwind | Info | tailwindcss without nesting plugin |
| 13 | T2 | Tailwind | Warning | tailwindcss after autoprefixer (wrong order) |
| 14 | T3 | Tailwind | Info | postcss-preset-env with tailwindcss (potential conflict) |
| 15 | X1 | Syntax/Parser | Warning | Both parser and syntax specified |
| 16 | X2 | Syntax/Parser | Info | Unknown parser value |
| 17 | X3 | Syntax/Parser | Info | Parser set but no matching preprocessor plugin |
| 18 | M1 | Source Maps | Info | Source maps disabled (map: false) |
| 19 | M2 | Source Maps | Info | Inline source maps enabled (map.inline: true) |
| 20 | B1 | Best Practices | Warning | No plugins configured |
| 21 | B2 | Best Practices | Info | Using postcss-preset-env AND individual feature plugins it includes |
| 22 | B3 | Best Practices | Info | Very large number of plugins (>15) |

## Output Formats

- `text` (default): Human-readable with severity icons
- `json`: Machine-parseable JSON with findings array and summary
- `summary`: Pass/fail with error/warning/info counts

## Exit Codes

- `0`: No errors (warnings/infos only or clean)
- `1`: One or more errors found
- `2`: File not found or invalid input

## Requirements

- Python 3.8+
- No external dependencies (pure stdlib)