postcss-best-practices

What this skill does

# PostCSS Best Practices

You are an expert in PostCSS, CSS processing pipelines, and modern CSS tooling.

## Key Principles

- Use PostCSS as a modular CSS processor with purpose-specific plugins
- Write future-proof CSS using modern syntax with appropriate transpilation
- Optimize CSS output for production with minification and autoprefixing
- Keep plugin configurations minimal and purposeful

## What is PostCSS

PostCSS is a tool for transforming CSS with JavaScript plugins. Unlike preprocessors (Sass/Less), PostCSS:
- Is modular - add only the features you need
- Can parse and transform standard CSS
- Enables future CSS syntax today
- Optimizes and minifies output
- Works with any build tool

## Project Setup

### Installation
```bash
# Core PostCSS
npm install postcss postcss-cli --save-dev

# Common plugins
npm install autoprefixer cssnano postcss-preset-env --save-dev

# Optional plugins
npm install postcss-import postcss-nested postcss-custom-media --save-dev
```

### Configuration File
```javascript
// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('postcss-preset-env')({
      stage: 2,
      features: {
        'nesting-rules': true,
        'custom-media-queries': true,
        'custom-properties': true,
      },
    }),
    require('autoprefixer'),
    require('cssnano')({
      preset: ['default', {
        discardComments: { removeAll: true },
      }],
    }),
  ],
};
```

### Build Tool Integration

#### Webpack
```javascript
// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          'postcss-loader',
        ],
      },
    ],
  },
};
```

#### Vite
```javascript
// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    postcss: './postcss.config.js',
  },
});
```

#### Next.js
```javascript
// postcss.config.js (auto-detected)
module.exports = {
  plugins: {
    'postcss-import': {},
    'tailwindcss/nesting': {},
    tailwindcss: {},
    autoprefixer: {},
  },
};
```

## Essential Plugins

### postcss-preset-env

Enables modern CSS features with polyfills:

```javascript
// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-preset-env')({
      stage: 2, // Stage 2 features are stable
      features: {
        'nesting-rules': true,
        'custom-media-queries': true,
        'custom-selectors': true,
        'gap-properties': true,
        'logical-properties-and-values': true,
      },
      autoprefixer: { grid: true },
      browsers: 'last 2 versions',
    }),
  ],
};
```

### autoprefixer

Adds vendor prefixes automatically:

```javascript
// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer')({
      grid: 'autoplace', // Enable grid prefixes
      flexbox: true,
    }),
  ],
};

// Input CSS
.element {
  display: flex;
  user-select: none;
}

// Output CSS
.element {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-user-select: none;
     -moz-user-select: none;
      -ms-user-select: none;
          user-select: none;
}
```

### cssnano

Minifies and optimizes CSS for production:

```javascript
// postcss.config.js
const isProduction = process.env.NODE_ENV === 'production';

module.exports = {
  plugins: [
    require('autoprefixer'),
    isProduction && require('cssnano')({
      preset: ['default', {
        discardComments: { removeAll: true },
        normalizeWhitespace: true,
        minifyFontValues: true,
        minifyGradients: true,
        reduceIdents: false, // Preserve animation names
        mergeRules: true,
        mergeLonghand: true,
      }],
    }),
  ].filter(Boolean),
};
```

### postcss-import

Inline @import statements:

```javascript
// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import')({
      path: ['src/styles'],
    }),
  ],
};
```

```css
/* main.css */
@import 'variables.css';
@import 'base.css';
@import 'components/buttons.css';
@import 'components/cards.css';
```

### postcss-nested

Enables Sass-like nesting:

```javascript
// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-nested'),
  ],
};
```

```css
/* Input */
.card {
  background: white;

  &__header {
    padding: 16px;
  }

  &__body {
    padding: 16px;
  }

  &:hover {
    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
  }

  @media (min-width: 768px) {
    display: flex;
  }
}

/* Output */
.card {
  background: white;
}
.card__header {
  padding: 16px;
}
.card__body {
  padding: 16px;
}
.card:hover {
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
}
@media (min-width: 768px) {
  .card {
    display: flex;
  }
}
```

## Modern CSS Features

### CSS Nesting (Native)
```css
/* Modern browsers support native nesting */
.card {
  background: white;
  border-radius: 8px;

  & .card-header {
    padding: 1rem;
    border-bottom: 1px solid #eee;
  }

  & .card-body {
    padding: 1rem;
  }

  &:hover {
    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
  }

  @media (min-width: 768px) {
    display: flex;
  }
}
```

### Custom Properties (CSS Variables)
```css
:root {
  /* Colors */
  --color-primary: #3498db;
  --color-primary-light: color-mix(in srgb, var(--color-primary), white 20%);
  --color-primary-dark: color-mix(in srgb, var(--color-primary), black 20%);
  --color-text: #333333;
  --color-background: #ffffff;
  --color-border: #e0e0e0;

  /* Typography */
  --font-family-base: 'Helvetica Neue', Arial, sans-serif;
  --font-size-base: 1rem;
  --line-height-base: 1.5;

  /* Spacing */
  --spacing-unit: 8px;
  --spacing-sm: calc(var(--spacing-unit) * 1);
  --spacing-md: calc(var(--spacing-unit) * 2);
  --spacing-lg: calc(var(--spacing-unit) * 3);
  --spacing-xl: calc(var(--spacing-unit) * 4);

  /* Transitions */
  --transition-base: 0.3s ease;

  /* Shadows */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
}

.button {
  padding: var(--spacing-sm) var(--spacing-md);
  background: var(--color-primary);
  color: white;
  transition: background var(--transition-base);
}

.button:hover {
  background: var(--color-primary-dark);
}
```

### Custom Media Queries
```css
/* Define custom media queries */
@custom-media --viewport-sm (min-width: 576px);
@custom-media --viewport-md (min-width: 768px);
@custom-media --viewport-lg (min-width: 992px);
@custom-media --viewport-xl (min-width: 1200px);

@custom-media --motion-ok (prefers-reduced-motion: no-preference);
@custom-media --dark-mode (prefers-color-scheme: dark);

/* Usage */
.element {
  width: 100%;
}

@media (--viewport-md) {
  .element {
    width: 50%;
  }
}

@media (--viewport-lg) {
  .element {
    width: 33.333%;
  }
}

@media (--motion-ok) {
  .element {
    transition: transform 0.3s ease;
  }
}
```

### Custom Selectors
```css
/* Define reusable selectors */
@custom-selector :--heading h1, h2, h3, h4, h5, h6;
@custom-selector :--button button, [type="button"], [type="submit"];
@custom-selector :--enter :hover, :focus;

/* Usage */
:--heading {
  font-family: var(--font-family-heading);
  line-height: 1.2;
  margin-bottom: 1rem;
}

:--button {
  cursor: pointer;
  font-family: inherit;
}

.link:--enter {
  color: var(--color-primary);
  text-decoration: underline;
}
```

### Logical Properties
```css
/* Use logical properties for internationalization */
.element {
  /* Instead of margin-left/right */
  margin-inline: auto;

  /* Instead of padding-top/bottom */
  padding-block: var(--spacing-md);

  /* Instead of width/height */
  inline-size: 100%;
  block-size: auto;

  /* Instead of border-left */
  border-inline-start: 2px solid var(--color-primary);

  /* Instead of text-align: left */
  text-align: start;
}
```

### Container Queries
```css
/* Modern container queries */
.card-container {
  container-type: inline-size;
  container-name: card;
}

.card {
  display: block;
}

@container card (min-width: 400px) {
  .car