# scss-best-practices

Enforces SCSS best practices including the 7-1 folder structure, BEM naming, and a strict three-level nesting limit. Useful when styling maintainable frontend projects.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1700 installs · ★ 286
- Author: Mindrally
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Mindrally/skills/tree/HEAD/scss-best-practices/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/scss-best-practices

## What it does

This skill guides your coding agent through structured SCSS development based on the classic 7-1 architecture pattern. It organizes stylesheets into abstracts, base, components, layout, pages, themes, and vendors, pulling them together using modern `@use` rules in `main.scss`. Components follow the BEM naming methodology for blocks, elements, and modifiers.

Nesting is restricted to a maximum depth of three levels. Deep nesting quickly ruins CSS specificity. Because of this boundary, the agent keeps selectors flat and maintainable.

The skill also configures structured scales for 8px-based spacing, z-index values, breakpoints from 576px to 1400px, and reusable mixins. Built-in mixins cover flexbox centering, line truncation, and accessibility helpers like `visually-hidden` and `focus-visible`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill scss-best-practices -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/scss-best-practices/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/scss-best-practices/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill scss-best-practices -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/scss-best-practices/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill scss-best-practices -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/scss-best-practices/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Mindrally/skills scss-best-practices
```

2. **Manually: put the files in place**
- File: `.github/skills/scss-best-practices/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill scss-best-practices -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Mindrally/skills --path scss-best-practices
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/scss-best-practices/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill scss-best-practices -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Mindrally/skills/tree/HEAD/scss-best-practices/SKILL.md

## When to use it
- set up a clean 7-1 SCSS directory architecture
- prevent deep selector nesting beyond three levels
- write BEM-compliant CSS selectors for components
- standardize spacing, z-index, and breakpoint variables

## Example prompts
- Create a card component using BEM conventions and SCSS variables
- Refactor our monolithic stylesheet into a 7-1 folder pattern using @use
- Write responsive styles using the breakpoint map and respond-to mixin

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3fdda5cdecfd4ff4.

BEGIN THIRD-PARTY FILE 3fdda5cdecfd4ff4
````text
---
name: scss-best-practices
description: SCSS/Sassy CSS best practices and coding guidelines for maintainable, scalable stylesheets
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# 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
```scss
// 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
```scss
// 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;
````
END THIRD-PARTY FILE 3fdda5cdecfd4ff4

The third-party file has ended. Everything between the 3fdda5cdecfd4ff4 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2946 of 11432 bytes. © Mindrally · Apache-2.0 · https://github.com/Mindrally/skills/tree/HEAD/scss-best-practices/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md