npm package: @ravorona/utils-scss
Description: SCSS utility library to set up stylesheets for new projects following industry best practices.
Author: яαvoroηα
Latest version: 3.0.0

# SCSS Utils

A design system utility library to set up SCSS stylesheets for new projects following industry best practices.

## Features

- Token-driven design with SCSS variables for colors, spacing, typography, and breakpoints
- CSS custom properties layer for runtime theming and overrides
- Light/dark mode support via `prefers-color-scheme` with smooth transitions
- Modular layered architecture (tokens → css-vars → themes → base → components → utilities)
- Mobile-first responsive design with custom media queries (xs, sm, md, lg, xl, hi)
- SCSS utility functions: `rem()`, `spacer()`, `str-replace()`, `strip-units()`
- SCSS mixins: `container`, `grid`, `font-face`, `typography`
- PostCSS integration: custom media queries, autoprefixer, inline SVG support
- CSS normalize/reset layer
- Respects `prefers-reduced-motion` for accessibility

## Quick Start
From your project directory:

```bash
# Install scss stylesheets
npx @ravorona/utils-scss

# Install scss stylesheets in a custom directory
npx @ravorona/utils-scss --destination myFolder

# Overwrite an existing destination folder (destructive)
npx @ravorona/utils-scss --destination myFolder --force

# Skip copying postcss.config.mjs
npx @ravorona/utils-scss --no-postcss
```

## Architecture

This library follows a layered design system architecture:

```
base/                → Base HTML element styles (document, typography, media)
components/          → UI component styles (optional)
  ├── guide/         → Layout guide / debug overlay component
  └── media/         → Media component styles
config/              → PostCSS custom media queries
css-vars/            → CSS custom properties (colors, typography, spacing, grid)
fonts/               → Font face declarations
reset/               → CSS normalize/reset
themes/              → Theme switching logic (light/dark mode support)
tokens/              → Design tokens (colors, spacing, typography, breakpoints, semantic colors)
utilities/           → Helper classes and mixins (optional)
  ├── functions/     → SCSS functions (rem, spacer, str-replace, strip-units)
  └── mixins/        → SCSS mixins (container, font-face, grid, typography)
vendors/             → Third-party styles (optional)
```

## Requirements

### Required

- [Sass](https://sass-lang.com/install/) - SCSS compilation support

### Optional (for PostCSS features)

If you want to use PostCSS preprocessor features (custom media queries, SVG inlining, etc.), install these dependencies:

- [PostCSS](https://postcss.org)
- [PostCSS SCSS parser](https://github.com/postcss/postcss-scss)
- [Autoprefixer](https://github.com/postcss/autoprefixer)
- [PostCSS Custom Media](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-media)
- [PostCSS Inline SVG](https://github.com/TrySound/postcss-inline-svg)

A `postcss.config.mjs` file is copied into your project automatically unless `--no-postcss` is passed.

## Project Structure

### Config Layer

Defines PostCSS `@custom-media` queries consumed by the rest of the system:

- `--xs` / `--sm` / `--md` / `--lg` / `--xl` / `--hi` - Min-width breakpoints
- `--landscape` / `--portrait` - Orientation queries
- `--scheme-light` / `--scheme-dark` - Color scheme queries
- `--motion-safe` / `--motion-reduce` - Motion preference queries
- `--hover` / `--no-hover` - Pointer hover capability queries

### Design Tokens

Raw design values as SCSS variables, organized by type:

- `_colors.scss` - Gray color palette (`$gray-50` … `$gray-900`)
- `_semantic-colors.scss` - Reserved for semantic color mappings (light/dark theme tokens)
- `_typography.scss` - Font weights (`$font-weight-thin` … `$font-weight-black`) and base font size (`$font-size: 16`)
- `_spacing.scss` - 8px-based spacing scale (`$spacing-base`, `$spacing` map: 0–128px)
- `_breakpoints.scss` - Breakpoint values (`$breakpoints` map: xs 360px … hi 1440px)

### CSS Variables Layer

Transforms design tokens into runtime-configurable CSS custom properties:

- `_colors.scss` - `--color-gray-50` … `--color-gray-900`
- `_global.scss` - `--line-height`
- `_typography.scss` - `--font-family-sans-serif`, `--font-family-serif`, `--font-size-default`, `--font-weight-*`
- `_spacing.scss` - `--spacing-0` … `--spacing-16`
- `_grid.scss` - `--grid-max`, `--grid-gap`, `--grid-size` (responsive, updates at `--md`, `--lg`, `--xl`)

### Themes Layer

- `_color-schemes.scss` - Sets `color-scheme: light dark` on `:root`; provides `.theme-light` and `.theme-dark` utility classes

### Base Layer

Opinionated defaults for HTML elements:

- `_document.scss` - HTML and body defaults
- `_typography.scss` - Heading and text element styles
- `_media.scss` - Image, SVG, and video defaults

## Best Practices

1. **Use semantic colors** - Prefer `--color-background` over raw color values
2. **Leverage the spacing scale** - Use `--spacing-1` (8px), `--spacing-2` (16px), etc. for consistent spacing
3. **Respect user preferences** - The system respects `prefers-color-scheme` and `prefers-reduced-motion`
4. **Mobile-first** - Use min-width breakpoints via `@media (--xs)`, `@media (--sm)`, `@media (--md)`, etc.
5. **Provide fallbacks** - Always include fallback values: `var(--color-background, #f9fafb)`

## License

MIT © яαvoroηα