@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 styled-components.

## 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 and combines:

- **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

## Features

### 🎨 **CSS Standards**
- Consistent color formatting (lowercase hex, short notation)
- Standardized units and measurements
- Proper spacing and indentation (2 spaces)
- Unix line endings

### 📐 **Property Ordering**
- Logical property order: box model → positioning → flexbox/grid → dimensions → spacing → borders → background → typography → animations
- Custom properties listed first
- Consistent declaration grouping

### 🔧 **SCSS Support**
- Variable naming conventions (`$variable-name`)
- Mixin and function naming patterns
- Import organization
- Placeholder selector standards

### 🚫 **Quality Rules**
- No duplicate selectors or properties
- Maximum selector specificity limits
- No vendor prefixes (use autoprefixer instead)
- No `!important` declarations
- Maximum 4 compound selectors

### 📏 **Formatting**
- 2-space indentation
- 100-character line length limit
- Single quotes for strings
- Always use semicolons
- Proper spacing around operators

## 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: Consistent naming and organization
$primary-color: #3498db;
$font-size-large: 1.25rem;
$border-radius-small: 0.25rem;

// ❌ Avoid: Inconsistent naming
$primaryColor: #3498db;
$font_size_large: 1.25rem;
```

### 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** 16+
- **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.