scss-best-practices

Q: How do I install scss-best-practices?

Run npx skills add https://github.com/mindrally/skills --skill scss-best-practices in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/scss-best-practices/ (personal) or .claude/skills/scss-best-practices/ (project).

by mindrallyCode Quality & Workflow

SCSS/Sassy CSS best practices and coding guidelines for maintainable, scalable stylesheets

Installs: 1.7K
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/mindrally/skills --skill scss-best-practices

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads scss-best-practices automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

SCSS Best Practices

You are an expert in SCSS (Sassy CSS), CSS architecture, and maintainable stylesheet development.

Key Principles

Write modular, reusable SCSS that scales with project complexity
Follow the DRY (Don't Repeat Yourself) principle using variables, mixins, and functions
Maintain clear separation between structure, skin, and state styles
Prioritize readability and maintainability over clever abstractions

File Organization

Architecture Pattern (7-1 Pattern)

scss/
├── abstracts/
│   ├── _variables.scss    # Global variables
│   ├── _functions.scss    # SCSS functions
│   ├── _mixins.scss       # Reusable mixins
│   └── _placeholders.scss # Extendable placeholders
├── base/
│   ├── _reset.scss        # CSS reset/normalize
│   ├── _typography.scss   # Typography rules
│   └── _base.scss         # Base element styles
├── components/
│   ├── _buttons.scss      # Button components
│   ├── _cards.scss        # Card components
│   └── _forms.scss        # Form components
├── layout/
│   ├── _header.scss       # Header layout
│   ├── _footer.scss       # Footer layout
│   ├── _grid.scss         # Grid system
│   └── _navigation.scss   # Navigation layout
├── pages/
│   ├── _home.scss         # Home page specific
│   └── _contact.scss      # Contact page specific
├── themes/
│   └── _default.scss      # Default theme
├── vendors/
│   └── _bootstrap.scss    # Third-party overrides
└── main.scss              # Main manifest file

Import Order

// main.scss
@use 'abstracts/variables';
@use 'abstracts/functions';
@use 'abstracts/mixins';
@use 'abstracts/placeholders';

@use 'vendors/normalize';

@use 'base/reset';
@use 'base/typography';
@use 'base/base';

@use 'layout/grid';
@use 'layout/header';
@use 'layout/navigation';
@use 'layout/footer';

@use 'components/buttons';
@use 'components/cards';
@use 'components/forms';

@use 'pages/home';

@use 'themes/default';

Variables

Naming Convention

// Use semantic, descriptive names
// Format: $category-property-variant

// Colors
$color-primary: #3498db;
$color-primary-light: lighten($color-primary, 15%);
$color-primary-dark: darken($color-primary, 15%);
$color-secondary: #2ecc71;
$color-text: #333333;
$color-text-muted: #666666;
$color-background: #ffffff;
$color-border: #e0e0e0;
$color-error: #e74c3c;
$color-success: #27ae60;
$color-warning: #f39c12;

// Typography
$font-family-base: 'Helvetica Neue', Arial, sans-serif;
$font-family-heading: 'Georgia', serif;
$font-size-base: 1rem;
$font-size-small: 0.875rem;
$font-size-large: 1.25rem;
$font-weight-normal: 400;
$font-weight-bold: 700;
$line-height-base: 1.5;

// Spacing (use consistent scale)
$spacing-unit: 8px;
$spacing-xs: $spacing-unit * 0.5;  // 4px
$spacing-sm: $spacing-unit;        // 8px
$spacing-md: $spacing-unit * 2;    // 16px
$spacing-lg: $spacing-unit * 3;    // 24px
$spacing-xl: $spacing-unit * 4;    // 32px
$spacing-xxl: $spacing-unit * 6;   // 48px

// Breakpoints
$breakpoint-sm: 576px;
$breakpoint-md: 768px;
$breakpoint-lg: 992px;
$breakpoint-xl: 1200px;
$breakpoint-xxl: 1400px;

// Z-index scale
$z-index-dropdown: 1000;
$z-index-sticky: 1020;
$z-index-fixed: 1030;
$z-index-modal-backdrop: 1040;
$z-index-modal: 1050;
$z-index-popover: 1060;
$z-index-tooltip: 1070;

// Transitions
$transition-base: 0.3s ease;
$transition-fast: 0.15s ease;
$transition-slow: 0.5s ease;

// Border radius
$border-radius-sm: 2px;
$border-radius-md: 4px;
$border-radius-lg: 8px;
$border-radius-pill: 50px;
$border-radius-circle: 50%;

// Shadows
$shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
$shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
$shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
$shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.15);

Maps for Related Values

// Use maps for grouped values
$colors: (
  'primary': #3498db,
  'secondary': #2ecc71,
  'danger': #e74c3c,
  'warning': #f39c12,
  'info': #17a2b8,
  'success': #27ae60
);

$breakpoints: (
  'sm': 576px,
  'md': 768px,
  'lg': 992px,
  'xl': 1200px,
  'xxl': 1400px
);

// Access with map-get
.element {
  color: map-get($colors, 'primary');
}

Mixins

Responsive Breakpoints

@mixin respond-to($breakpoint) {
  @if map-has-key($breakpoints, $breakpoint) {
    @media (min-width: map-get($breakpoints, $breakpoint)) {
      @content;
    }
  } @else {
    @warn "Unknown breakpoint: #{$breakpoint}";
  }
}

// Usage
.element {
  width: 100%;

  @include respond-to('md') {
    width: 50%;
  }

  @include respond-to('lg') {
    width: 33.333%;
  }
}

Flexbox Utilities

@mixin flex-center {
  display: flex;
  align-items: center;
  justify-content: center;
}

@mixin flex-between {
  display: flex;
  align-items: center;
  justify-content: space-between;
}

@mixin flex-column {
  display: flex;
  flex-direction: column;
}

Typography

@mixin font-size($size, $line-height: null) {
  font-size: $size;
  @if $line-height {
    line-height: $line-height;
  }
}

@mixin truncate($lines: 1) {
  @if $lines == 1 {
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
  } @else {
    display: -webkit-box;
    -webkit-line-clamp: $lines;
    -webkit-box-orient: vertical;
    overflow: hidden;
  }
}

Accessibility

@mixin visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

@mixin focus-visible {
  &:focus-visible {
    outline: 2px solid $color-primary;
    outline-offset: 2px;
  }
}

BEM Naming Convention

Structure

// Block: Standalone component
// Element: Part of block (block__element)
// Modifier: Variant (block--modifier or block__element--modifier)

.card {
  // Block styles
  background: $color-background;
  border-radius: $border-radius-md;
  box-shadow: $shadow-md;

  // Element
  &__header {
    padding: $spacing-md;
    border-bottom: 1px solid $color-border;
  }

  &__title {
    margin: 0;
    font-size: $font-size-large;
    font-weight: $font-weight-bold;
  }

  &__body {
    padding: $spacing-md;
  }

  &__footer {
    padding: $spacing-md;
    border-top: 1px solid $color-border;
  }

  // Modifier
  &--featured {
    border: 2px solid $color-primary;
  }

  &--compact {
    .card__header,
    .card__body,
    .card__footer {
      padding: $spacing-sm;
    }
  }
}

Nesting Rules

Maximum Nesting Depth

// BAD: Too deep nesting
.nav {
  .nav-list {
    .nav-item {
      .nav-link {
        .nav-icon {
          // 5 levels deep - avoid this
        }
      }
    }
  }
}

// GOOD: Keep nesting to 3 levels maximum
.nav {
  // Level 1
}

.nav__list {
  // Level 1
}

.nav__item {
  // Level 1
}

.nav__link {
  color: $color-text;

  &:hover,
  &:focus {
    // Level 2 - acceptable for states
    color: $color-primary;
  }

  &--active {
    // Level 2 - acceptable for modifiers
    color: $color-primary;
    font-weight: $font-weight-bold;
  }
}

Acceptable Nesting

.component {
  // Direct child pseudo-elements
  &::before,
  &::after {
    content: '';
  }

  // State modifiers
  &:hover,
  &:focus,
  &:active {
    // State styles
  }

  // BEM modifiers
  &--variant {
    // Modifier styles
  }

  // Media queries
  @include respond-to('md') {
    // Responsive styles
  }
}

Functions

Color Functions

@function tint($color, $percentage) {
  @return mix(white, $color, $percentage);
}

@function shade($color, $percentage) {
  @return mix(black, $color, $percentage);
}

// Usage
.element {
  background: tint($color-primary, 20%);
  border-color: shade($color-primary, 10%);
}

Unit Conversion

@function px-to-rem($px, $base: 16) {
  @return ($px / $base) * 1rem;
}

@function rem-to-px($rem, $base: 16) {
  @return ($rem / 1rem) * $base * 1px;
}

// Usage
.element {
  font-size: px-to-rem(18); // 1.125rem
  padding: px-to-rem(24);   // 1.5rem
}

Spacing Function

@function spacing($multiplier) {
  @return $spacing-unit * $multiplier;
}

// Usage
.element {
  margin-bottom: spacing(2); // 16px
  padding: spacing(3);       // 24px
}

Extend and Placeholders

Use Placeholders Over Classes

// Define placeholder
%button-base {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: $spacing-sm $spacing-md;
  border: none;
  border-radius: $border-radius-md;
  font-family: inherit;
  font-size: $font-size-base;
  font-weight: $font-weight-bold;
  text-decoration: none;
  cursor: pointer;
  transition: all $transition-base;

  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
}

// Extend placeholder
.btn-primary {
  @extend %button-base;
  background: $color-primary;
  color: white;

  &:hover:not(:disabled) {
    background: darken($color-primary, 10%);
  }
}

.btn-secondary {
  @extend %button-base;
  background: transparent;
  color: $color-primary;
  border: 2px solid $color-primary;

  &:hover:not(:disabled) {
    background: $color-primary;
    color: white;
  }
}

Loops and Iteration

Generate Utility Classes

// Spacing utilities
$spacing-directions: (
  '': '',
  't': '-top',
  'r': '-right',
  'b': '-bottom',
  'l': '-left',
  'x': '-inline',
  'y': '-block'
);

@each $abbr, $direction in $spacing-directions {
  @for $i from 0 through 8 {
    .m#{$abbr}-#{$i} {
      margin#{$direction}: spacing($i);
    }
    .p#{$abbr}-#{$i} {
      padding#{$direction}: spacing($i);
    }
  }
}

// Color utilities
@each $name, $color in $colors {
  .text-#{$name} {
    color: $color;
  }
  .bg-#{$name} {
    background-color: $color;
  }
  .border-#{$name} {
    border-color: $color;
  }
}

Performance Best Practices

Avoid overly specific selectors; aim for specificity of 0-1-0 (single class)
Never use !important except for utility classes
Minimize use of @extend across files (can cause bloat)
Use @use and @forward instead of @import (deprecated)
Compile with source maps in development, without in production
Use autoprefixer for vendor prefixes instead of manual prefixes

Modern SCSS Features

Module System

// _variables.scss
$primary: #3498db;

// _mixins.scss
@use 'variables' as vars;

@mixin themed-button {
  background: vars.$primary;
}

// main.scss
@use 'mixins';

.button {
  @include mixins.themed-button;
}

Built-in Modules

@use 'sass:math';
@use 'sass:color';
@use 'sass:list';
@use 'sass:map';
@use 'sass:string';

.element {
  width: math.div(100%, 3);
  background: color.adjust($color-primary, $lightness: 10%);
}

Code Style

Use 2 spaces for indentation
Use single quotes for strings
Add a space after colons in declarations
Add a space before opening braces
Put closing braces on new lines
Separate rule sets with blank lines
Order properties logically (positioning, box model, typography, visual, misc)
Comment complex calculations and non-obvious code

FAQ

What does the scss-best-practices skill do?

SCSS/Sassy CSS best practices and coding guidelines for maintainable, scalable stylesheets

How do I install scss-best-practices?

Run npx skills add https://github.com/mindrally/skills --skill scss-best-practices in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/scss-best-practices/ (personal) or .claude/skills/scss-best-practices/ (project).

Which AI agents can use scss-best-practices?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is scss-best-practices safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains scss-best-practices?

It is published by mindrally in mindrally/skills. It has 1,676 recorded installs.

More from mindrally/skills

View all →

fastapi-python

mindrally/skills

Expert in FastAPI Python development with best practices for APIs and async operations

Backend & APIs13.9K installs

nextjs-react-typescript

mindrally/skills

Expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI and Tailwind

Frontend & Design5.3K installs

web-scraping

mindrally/skills

Expert in web scraping and data extraction with Python tools

Productivity & Automation4.5K installs

computer-vision-opencv

mindrally/skills

Expert guidance for computer vision development using OpenCV, PyTorch, and modern deep learning techniques for image and video processing.

Media & Creative3.8K installs

framer-motion

mindrally/skills

Expert guidelines for building performant animations with Framer Motion/Motion library in React applications

Frontend & Design3K installs

chrome-extension-development

mindrally/skills

Expert guidelines for Chrome extension development with Manifest V3, covering security, performance, and best practices. Use when building browser extensions, creating popup UIs, implementing content scripts, working with Chrome APIs, managing extension permissions, or publishing to Chrome Web Store.

Code Quality & Workflow2.8K installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs

scss-best-practices

Install

Install

Describe the task

Review the result

SKILL.md

SCSS Best Practices

Key Principles

File Organization

Architecture Pattern (7-1 Pattern)

Import Order

Variables

Naming Convention

Maps for Related Values

Mixins

Responsive Breakpoints

Flexbox Utilities

Typography

Accessibility

BEM Naming Convention

Structure

Nesting Rules

Maximum Nesting Depth

Acceptable Nesting

Functions

Color Functions

Unit Conversion

Spacing Function

Extend and Placeholders

Use Placeholders Over Classes

Loops and Iteration

Generate Utility Classes

Performance Best Practices

Modern SCSS Features

Module System

Built-in Modules

Code Style

FAQ

More from mindrally/skills

Popular code quality & workflow skills