@aleph/stylelint-config/README.md

Aleph's StyleLint configuration for CSS, SCSS, and styled-components

# @aleph/stylelint-config

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

## Installation

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

## Usage

### Basic Setup

Create or update your `stylelint.config.js`:

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

Or using the `stylelint.config.json` format:

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

### Package.json Script

Add to your `package.json`:

```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:

```javascript
// 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`:

```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:

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

## Common Patterns

### SCSS Variables

```scss
// ✅ 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

```scss
// ✅ 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

```scss
// ✅ 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](https://docs.aleph.inc/docs/resources/4devs/standards/code-style-standards)**

## License

MIT © Aleph Inc.