Skip to content

Latest commit

 

History

History
295 lines (223 loc) · 6.48 KB

sort-custom-properties.md

File metadata and controls

295 lines (223 loc) · 6.48 KB
pageClass sidebarDepth title description frameworks since
rule-details
0
tailwind-variants/sort-custom-properties
enforce consistent ordering of CSS custom properties (CSS variables)
agnostic
v2.0.0

tailwind-variants/sort-custom-properties

enforce consistent ordering of CSS custom properties (CSS variables)

📖 Rule Details

This rule enforces a consistent ordering of CSS custom properties (CSS variables) within CSS blocks. By default, properties are organized into logical groups (spacing, font, transition, color) with alphabetical ordering within each group. Properties that don't match any specified pattern are placed at the end.

The rule works with various CSS syntaxes including standard CSS, Tailwind CSS @theme and @utility blocks.

🔧 Options

{
  "tailwind-variants/sort-custom-properties": [
    "error",
    {
      "order": [
        "^--spacing-",
        "^--size-",
        "^--font-",
        "^--weight-",
        "^--leading-",
        "^--tracking-",
        "^--radius-",
        "^--shadow-",
        "^--animate-",
        "^--transition-",
        "^--color-"
      ],
      "emptyLineBetweenGroups": false
    }
  ]
}
  • order (string[]) ... Array of regex patterns defining the sort order for custom properties. Default is ["^--spacing-", "^--size-", "^--font-", "^--weight-", "^--leading-", "^--tracking-", "^--radius-", "^--shadow-", "^--animate-", "^--transition-", "^--color-"].
  • emptyLineBetweenGroups (boolean) ... Whether to enforce empty lines between different property groups. Default is false.

{ "order": ["^--spacing-", "^--size-", "^--font-", "^--weight-", "^--leading-", "^--tracking-", "^--radius-", "^--shadow-", "^--animate-", "^--transition-", "^--color-"] } (default)

/* ✓ GOOD */
:root {
  --spacing-lg: 2rem;
  --spacing-sm: 1rem;
  --font-family: Arial;
  --font-size: 16px;
  --transition-duration: 300ms;
  --transition-easing: ease-in-out;
  --color-primary: #007bff;
  --color-secondary: #6c757d;
}
/* ✗ BAD */
:root {
  --color-primary: #007bff;
  --font-family: Arial;
  --spacing-lg: 2rem;
  --transition-duration: 300ms;
}

{ order: ['^--color-', '^--font-'] }

/* ✓ GOOD */
:root {
  --color-primary: #007bff;
  --color-secondary: #6c757d;
  --font-family: Arial;
  --font-size: 16px;
  --spacing-lg: 2rem; /* Unmatched patterns go to end */
}

{ emptyLineBetweenGroups: true }

/* ✓ GOOD */
:root {
  --spacing-lg: 2rem;
  --spacing-sm: 1rem;

  --font-family: Arial;
  --font-size: 16px;

  --color-primary: #007bff;
}
/* ✗ BAD */
:root {
  --spacing-lg: 2rem;
  --font-family: Arial;
  --color-primary: #007bff;
}

⚙️ Pattern Matching

The rule supports various regex patterns for flexible ordering:

Prefix Patterns

/* ✓ GOOD */
:root {
  --button-bg: blue;
  --button-text: white;
  --input-border: gray;
  --input-focus: blue;
}

Suffix Patterns

/* ✓ GOOD */
:root {
  --button-size: large;
  --input-size: medium;
  --primary-color: blue;
  --secondary-color: red;
}

Exact Name Patterns

/* ✓ GOOD */
:root {
  --z-index: 999;
  --opacity: 0.8;
  --color-primary: blue; /* Other properties go to end */
}

Substring Patterns

/* ✓ GOOD */
:root {
  --dark-primary: black;
  --dark-secondary: gray;
  --light-primary: white;
  --light-secondary: lightgray;
  --primary-font: Arial; /* No match, goes to end */
}

✨ Supported Syntaxes

Standard CSS

/* ✓ GOOD */
:root {
  --spacing-lg: 2rem;
  --font-family: Arial;
  --color-primary: #007bff;
}

.component {
  --spacing-sm: 1rem;
  --font-size: 14px;
}

Tailwind CSS Syntax

/* ✓ GOOD */
@theme {
  --spacing-lg: 2rem;
  --font-family: Arial;
  --color-primary: #007bff;
}

@utility example {
  --spacing-sm: 1rem;
  --font-size: 16px;
  --color-text: #333;
}

Mixed Properties

/* ✓ GOOD */
:root {
  display: flex; /* Regular properties are not affected */
  margin: 0;
  --spacing-lg: 2rem; /* Custom properties are sorted */
  --font-family: Arial;
  --color-primary: #007bff;
}

🔧 Auto-fix

This rule provides auto-fix functionality. It will automatically:

  • Reorder custom properties according to the configured pattern order
  • Sort properties alphabetically within each group
  • Add or remove empty lines between groups when emptyLineBetweenGroups is configured

Before:

:root {
  --color-primary: #007bff;
  --font-family: Arial;
  --spacing-lg: 2rem;
}

After auto-fix:

:root {
  --spacing-lg: 2rem;
  --font-family: Arial;
  --color-primary: #007bff;
}

🚀 Version

This rule was introduced in eslint-plugin-tailwind-variants v2.0.0

🔍 Implementation