@aleph/stylelint-config

Aleph's StyleLint configuration for CSS, SCSS, and CSS modules.

Installation

npm install @aleph/stylelint-config --save-dev

Usage

Basic Setup

Create or update your stylelint.config.js:

module.exports = {
  extends: ['@aleph/stylelint-config']
};

Or using the stylelint.config.json format:

{
  "extends": ["@aleph/stylelint-config"]
}

Package.json Script

Add to your package.json:

{
  "scripts": {
    "lint:css": "stylelint '**/*.{css,scss}'",
    "lint:css:fix": "stylelint '**/*.{css,scss}' --fix"
  }
}

What's Included

This configuration extends:

• stylelint-config-standard: The standard shareable config for StyleLint
• stylelint-config-standard-scss: Standard config for SCSS
• stylelint-order: Property ordering rules
• stylelint-scss: SCSS-specific linting rules

Philosophy

This config follows a minimal override philosophy - we extend proven standard configs and only add rules where Aleph has specific needs. Most formatting and basic rules come from the standard configs.

Aleph-Specific Rules

🚫 Disabled Rules (For Flexibility)

• CSS-in-JS Compatibility: Allows mixed case for better styled-components integration
• Flexible Spacing: Disabled strict empty line requirements for developer convenience
• Modern CSS: Disabled some newer CSS validation rules that can be overly restrictive

📏 Aleph Constraints

• No !important declarations: Stricter than default - forces proper CSS architecture
• Selector Limits: Max 4 compound selectors, no ID selectors, specificity caps
• CSS-in-JS Support: Allows global and local pseudo-classes

📐 Property Ordering

Logical property order enforced:

• Custom properties first
• Display & layout → Grid/Flexbox → Dimensions → Spacing → Borders → Background → Typography → Visual effects

🔧 SCSS Flexibility

• Allows flexible naming patterns (overrides standard kebab-case requirements)
• Permits vendor prefixes when needed (for legacy browser support)

File Support

This configuration works with:

• CSS files (.css)
• SCSS files (.scss)
• Sass files (.sass)
• Styled-components (in JS/TS files)
• CSS Modules
• PostCSS files

Customization

Project-Specific Rules

If your project needs specific rules, extend our base config:

// stylelint.config.js
module.exports = {
  extends: ['@aleph/stylelint-config'],
  rules: {
    // Project-specific overrides
    'max-line-length': 120, // Longer lines for this project
    'selector-max-id': 1, // Allow one ID selector
  },
  overrides: [
    {
      files: ['**/*.scss'],
      rules: {
        // SCSS-specific rules
        'scss/dollar-variable-pattern': null, // Disable variable naming pattern
      },
    },
  ],
};

When to Override

Only override rules when you have a specific need:

• Legacy codebases that can't be easily updated
• Third-party CSS that doesn't follow conventions
• Generated styles from tools
• Specific design system requirements

IDE Integration

VS Code Setup

Install the StyleLint extension and add to .vscode/settings.json:

{
  "stylelint.enable": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": true
  },
  "css.validate": false,
  "scss.validate": false
}

CI/CD Integration

Add linting to your CI pipeline:

# Example GitHub Actions
- name: Lint CSS
  run: |
    npm ci
    npm run lint:css

Common Patterns

SCSS Variables

// ✅ Good: Standard kebab-case (enforced by stylelint-config-standard-scss)
$primary-color: #3498db;
$font-size-large: 1.25rem;
$border-radius-small: 0.25rem;

// ⚠️ Allowed: Flexible naming (Aleph override allows other patterns)
$primaryColor: #3498db;   // camelCase allowed
$font_size_large: 1.25rem;  // snake_case allowed
$PRIMARY_COLOR: #3498db;  // UPPER_CASE allowed

Property Ordering

// ✅ Good: Logical property order
.component {
  // Custom properties first
  --local-color: red;

  // Box model
  display: flex;
  
  // Positioning
  position: relative;
  top: 0;
  
  // Flexbox
  flex-direction: column;
  align-items: center;
  
  // Dimensions
  width: 100%;
  height: auto;
  
  // Spacing
  margin: 1rem;
  padding: 0.5rem;
  
  // Borders
  border: 1px solid #ccc;
  border-radius: 0.25rem;
  
  // Background
  background-color: white;
  
  // Typography
  color: #333;
  font-size: 1rem;
  
  // Other
  opacity: 1;
  cursor: pointer;
}

Selector Structure

// ✅ Good: Simple, specific selectors
.component {
  &__element {
    // Element styles
  }
  
  &--modifier {
    // Modifier styles
  }
  
  &:hover {
    // Pseudo-class styles
  }
}

// ❌ Avoid: Overly complex selectors
.page .sidebar .widget .component .element.active {
  // Too specific and hard to maintain
}

Troubleshooting

Common Issues

| Error | Cause | Solution | |-------|--------|----------| | Unexpected unknown at-rule | Using SCSS syntax in CSS file | Use .scss extension or configure parser | | Expected single space before "{" | Missing space before opening brace | Add space: .class { | | Unexpected vendor-prefix | Using vendor prefixes | Remove prefixes, use autoprefixer | | Expected newline after "," | Selector list formatting | Put each selector on new line |

Performance

For large projects, consider:

• Using .stylelintignore to exclude build directories
• Running StyleLint only on changed files in CI
• Using --cache flag for faster subsequent runs

Requirements

• Node.js 22+
• StyleLint 16+

Documentation

For detailed information about our code style standards and the rationale behind these rules, visit our documentation:

👉 Aleph Code Style Standards

License

MIT © Aleph Inc.