Stylelint Configuration Skill

Purpose

Generate Stylelint configuration for linting CSS, SCSS, and Vue component styles with automatic detection of stylesheet type and latest package versions.

🚨 MANDATORY FILE COUNT

Expected Output: 1 file

• .stylelintrc (primary format, JSON)

Alternative formats (if .stylelintrc is deprecated):

• .stylelintrc.json
• .stylelintrc.cjs
• .stylelintrc.js
• .stylelintrc.yaml / .stylelintrc.yml

🔍 BEFORE GENERATING - CRITICAL RESEARCH REQUIRED

Perform these checks in order before generating the configuration:

1. Stylelint Version: Fetch latest stable version

   • Run: npm view stylelint version
   • Use: ^{latest_version} in package.json
   • If version >= 16.0.0: Use new plugin system (verify breaking changes)

2. Stylesheet Type Detection: Determine CSS vs SCSS usage

   • Check package.json dependencies:
     • If sass or node-sass found → Use SCSS config
     • If neither found → Use standard CSS config
   • Check project files:
     • Search for **/*.scss files in src/ directory
     • If SCSS files found → Use SCSS config
     • If only CSS files → Use standard CSS config

3. Config Package Selection (based on step 2):

   • For SCSS projects:
     • Run: npm view stylelint-config-standard-scss version
     • Use: stylelint-config-standard-scss at ^{latest_version}
   • For CSS projects:
     • Run: npm view stylelint-config-standard version
     • Use: stylelint-config-standard at ^{latest_version}

4. Vue Configuration: Always include for Vue projects

   • Run: npm view stylelint-config-recommended-vue version
   • Use: stylelint-config-recommended-vue at ^{latest_version}
   • Note: Works with both CSS and SCSS in Vue SFCs

5. Verify Configuration Format: Check if .stylelintrc is still supported

   • Run: npm view stylelint peerDependencies
   • If .stylelintrc deprecated: Use .stylelintrc.json or .stylelintrc.cjs
   • Default: Use .stylelintrc (JSON format)

6. Check Rule Compatibility: Verify rules haven't been deprecated

   • Check: https://stylelint.io/user-guide/rules/
   • Common deprecations to watch:
     • unit-allowed-list (verify still exists)
     • color-function-notation (check valid values)
     • alpha-value-notation (verify syntax)
   • If rules deprecated: Remove or replace with current alternatives

7. Lint-Staged Integration: Check if stylelint should be added to lint-staged

   • Check if .lintstagedrc or .lintstagedrc.cjs exists:
     • If exists → CROSS-CHECK: Verify stylelint is included
     • If missing stylelint → RECOMMEND: Add to lint-staged config
   • Suggested lint-staged pattern:

     '**/*.{css,scss,vue}': 'stylelint --fix'
     

   • Action: If lint-staged exists but missing stylelint, notify user to update

8. PostCSS Integration (optional): Check if PostCSS is used

   • If postcss.config.js exists → Ensure compatibility
   • If Tailwind CSS detected → Add Tailwind-specific rules

Execution Checklist

Execute in this order:

• 1. Fetch latest stylelint version from npm
• 2. Detect stylesheet type (SCSS vs CSS) from package.json and file structure
• 3. Fetch latest version of appropriate config package:
  • stylelint-config-standard-scss (if SCSS detected)
  • stylelint-config-standard (if only CSS)
• 4. Fetch latest stylelint-config-recommended-vue version
• 5. Verify .stylelintrc format is still supported
• 6. Verify all rules in template are still valid
• 7. Check if lint-staged config exists and includes stylelint
• 8. Generate .stylelintrc file with detected configuration
• 9. Run validation script to confirm file exists and is valid JSON

Output

Primary Format: .stylelintrc (JSON)

For SCSS Projects:

{
  "extends": [
    "stylelint-config-standard-scss",
    "stylelint-config-recommended-vue"
  ],
  "rules": {
    // See examples.md for complete rule configuration
  }
}

For CSS Projects:

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-recommended-vue"
  ],
  "rules": {
    // See examples.md for complete rule configuration
  }
}

🛑 BLOCKING VALIDATION CHECKPOINT

After generating the file, run this validation:

#!/bin/bash

# Validate .stylelintrc exists and is valid JSON
STYLELINT_FILES=(".stylelintrc" ".stylelintrc.json" ".stylelintrc.cjs" ".stylelintrc.js")
FOUND=false

for file in "${STYLELINT_FILES[@]}"; do
  if [ -f "$file" ]; then
    FOUND=true
    echo "✓ Found: $file"
    
    # Validate JSON format (if .stylelintrc or .json)
    if [[ "$file" == *.stylelintrc ]] || [[ "$file" == *.json ]]; then
      if ! jq empty "$file" 2>/dev/null; then
        echo "✗ ERROR: $file is not valid JSON"
        exit 1
      fi
    fi
    
    # Validate required extends
    if [[ "$file" == *.stylelintrc ]] || [[ "$file" == *.json ]]; then
      if ! grep -q "stylelint-config-" "$file"; then
        echo "✗ ERROR: Missing stylelint-config-* in extends"
        exit 1
      fi
      
      if ! grep -q "stylelint-config-recommended-vue" "$file"; then
        echo "✗ WARNING: Missing Vue config (expected for Vue projects)"
      fi
    fi
    
    break
  fi
done

if [ "$FOUND" = false ]; then
  echo "✗ ERROR: No stylelint configuration file found"
  echo "Expected one of: ${STYLELINT_FILES[@]}"
  exit 1
fi

# Check if lint-staged exists and includes stylelint
LINTSTAGED_FILES=(".lintstagedrc" ".lintstagedrc.json" ".lintstagedrc.cjs" ".lintstagedrc.js")
for file in "${LINTSTAGED_FILES[@]}"; do
  if [ -f "$file" ]; then
    if ! grep -q "stylelint" "$file"; then
      echo "⚠️ RECOMMENDATION: Add stylelint to $file for pre-commit linting"
      echo "   Suggested pattern: '**/*.{css,scss,vue}': 'stylelint --fix'"
    else
      echo "✓ Stylelint integrated with lint-staged"
    fi
    break
  fi
done

echo "✓ Stylelint configuration validation passed"

Validation Requirements:

1. ✅ Stylelint config file exists (any supported format)
2. ✅ File is valid JSON/JavaScript syntax
3. ✅ Contains extends array with config packages
4. ✅ Includes stylelint-config-recommended-vue for Vue projects
5. ⚠️ Check lint-staged integration (warning if missing)

Template Reference

See: examples.md in this directory for:

• Complete .stylelintrc examples (SCSS and CSS variants)
• Detailed rule explanations with why each rule is configured
• Package version verification commands
• Lint-staged integration examples
• Common issues and troubleshooting
• Rule migration guide for deprecated options

Notes

Key Features

• Automatic Detection: SCSS vs CSS based on project dependencies and files
• Latest Versions: Always fetch current stable versions from npm
• Vue Support: Includes Vue SFC style linting
• Flexible Rules: Balanced between strictness and developer experience
• Lint-Staged Ready: Integrates with pre-commit hooks
• Format Flexibility: Supports multiple config formats with validation

Rule Philosophy

• Extends standard configs: Leverage community best practices
• Minimal overrides: Only disable overly restrictive rules
• Allow common units: px, rem, em, %, vh, vw, deg, fr, s, in
• Disable vendor prefix warnings: Required for browser compatibility
• Relaxed patterns: No strict class naming enforcement
• SCSS-specific: Space after variable colons for consistency

Configuration Strategy

• Standard SCSS/CSS: Primary configuration source
• Vue-specific: Handles <style> blocks in .vue files
• Legacy notation: color-function-notation: "legacy" for rgb()/rgba()
• Import flexibility: String notation for @use/@import
• No descending specificity checks: Too strict for real-world CSS

Lint-Staged Integration

• Pattern: **/*.{css,scss,vue} matches all style files
• Auto-fix: Use stylelint --fix to auto-fix issues
• Performance: Only lint changed files in pre-commit
• Cross-skill coordination: Check if lintstagedrc skill added stylelint

Maintenance Considerations

• Stylelint 16+: Major version with breaking changes (verify compatibility)
• Rule deprecations: Check release notes for removed/renamed rules
• Config package updates: Standard configs may change rule defaults
• Vue config compatibility: Ensure works with current Vue version
• Format migration: Be ready to switch from .stylelintrc to .stylelintrc.json