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:

# 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 - 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
• PostCSS SCSS parser
• Autoprefixer
• PostCSS Custom Media
• 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ηα