# Sass > Sass (Dart Sass) rules - SCSS syntax, variables, mixins, partials, @use/@forward, modules, 7-1 architecture, framework integration - Skill: `14bryanespinoza/sass` (Agent Skill) - Install (CLI): `npx skillmds@latest add 14bryanespinoza/sass` - Raw SKILL.md: https://api.skillmd.com/api/skills/14bryanespinoza/sass/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: 14BryanEspinoza (https://skillmd.com/u/14bryanespinoza) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/14bryanespinoza/sass --- # Sass — Rules and Conventions --- ## 1. Philosophy 1. **Dart Sass only** — Reference implementation. Node Sass deprecated. 2. **SCSS syntax** — CSS-compatible. No indented syntax. 3. **@use over @import** — Modules with namespaces. No global namespace pollution. 4. **Variables for tokens** — Colors, spacing, radii, fonts as variables. 5. **Mixins for patterns** — Reusable style blocks with arguments. --- ## 2. Minimum Version | Technology | Minimum Version | | ---------- | --------------- | | Dart Sass | 1.70+ | | Node.js | 22+ | | pnpm | 11+ | --- ## 3. Installation ```bash pnpm add -D sass ``` ### package.json scripts ```json { "scripts": { "sass:build": "sass src/styles:dist/styles --style=compressed --no-source-map", "sass:watch": "sass src/styles:dist/styles --watch" } } ``` --- ## 4. Syntax (SCSS) ```scss // Variables $primary: #0066cc; $spacing: 1rem; // Nesting .card { padding: $spacing; &:hover { background: lighten($primary, 20%); } .title { font-weight: 600; } } // Partials (imported via @use) @use "variables"; @use "mixins"; ``` --- ## 5. Variables ```scss // Global (with !default for overrides) $primary: #0066cc !default; $font-stack: "Inter", system-ui, sans-serif !default; $breakpoints: ( "sm": 576px, "md": 768px, "lg": 992px, "xl": 1200px, "xxl": 1400px, ) !default; // Scoped (in module) @use "config" as *; $local-var: 1rem; // Only in this file ``` ### Rules - **`!default`** on all config variables — allows overriding - **Descriptive names** — `$primary` not `$blue` - **Maps for related values** — breakpoints, colors, shadows --- ## 6. Nesting ```scss // Selector nesting .nav { display: flex; &-item { padding: 0.5rem 1rem; } &-link { color: $primary; &:hover { color: darken($primary, 10%); } } } // Property nesting .border { border: { style: solid; width: 1px; color: $gray-300; } } // Media queries .component { @media (min-width: 768px) { display: grid; } } ``` ### Rules Nesting - **Max 3 levels deep** — avoid overly specific selectors - **`&` for parent reference** — required for pseudo-classes, modifiers - **Media queries inside component** — keeps related styles together --- ## 7. Mixins & @include ```scss // Basic mixin @mixin flex-center { display: flex; justify-content: center; align-items: center; } // With arguments @mixin button-variant($bg, $color: white) { background: $bg; color: $color; border: none; padding: 0.5rem 1rem; border-radius: 0.375rem; &:hover { background: darken($bg, 10%); } } // With content block @mixin media-query($breakpoint) { @media (min-width: $breakpoint) { @content; } } // Usage .btn-primary { @include button-variant($primary); } .card { @include media-query(768px) { padding: 2rem; } } ``` ### Rules Mixins - **Prefix with category** — `button-variant`, `media-query`, `visually-hidden` - **Default arguments** — flexible without required params - **`@content` for blocks** — enables wrapper patterns --- ## 8. Modules (@use / @forward) ### @use (import with namespace) ```scss // styles/main.scss @use "variables" as *; // No namespace (globals) @use "mixins" as mx; // mx.flex-center() @use "functions" as fn; // fn.rem(16) @use "bootstrap/scss/bootstrap" as bs with ( $primary: #0066cc ); ``` ### @forward (re-export) ```scss // _index.scss (barrel file) @forward "variables"; @forward "mixins"; @forward "functions"; // main.scss @use "abstracts" as *; // Gets all forwarded members ``` ### Rules Modules - **`@use` once per file** — cached, no duplicate CSS - **`as *` sparingly** — only for true globals (variables) - **`@forward` for public API** — hide implementation partials - **`with ($var: value)`** — configure upstream modules --- ## 9. Functions (Essential) ```scss // Rem conversion @function rem($px, $base: 16px) { @return ($px / $base) * 1rem; } // Fluid type (clamp) @function fluid($min, $max, $vw: 1vw) { @return clamp($min, $vw, $max); } // Color manipulation @function theme-color($name) { @return map-get($theme-colors, $name); } ``` ### Built-in functions (use instead of custom) | Category | Functions | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Color** | `lighten`, `darken`, `mix`, `adjust-hue`, `saturate`, `desaturate`, `grayscale`, `complement`, `invert`, `alpha`, `opacity` | | **Math** | `percentage`, `round`, `ceil`, `floor`, `abs`, `min`, `max`, `random`, `unit`, `unitless`, `comparable` | | **String** | `quote`, `unquote`, `to-upper-case`, `to-lower-case`, `str-length`, `str-slice`, `str-insert`, `str-index` | | **List/Map** | `length`, `nth`, `set-nth`, `join`, `append`, `zip`, `index`, `map-get`, `map-set`, `map-merge`, `map-remove`, `map-keys`, `map-values`, `map-has-key` | | **Selector** | `selector-nest`, `selector-append`, `selector-extend`, `selector-replace`, `selector-unify`, `is-superselector`, `simple-selectors` | --- ## 10. Maps & Lists (Essential) ```scss // Map $theme-colors: ( "primary": #0066cc, "secondary": #6c757d, "success": #198754, ); // Iterate @each $name, $color in $theme-colors { .btn-#{$name} { @include button-variant($color); } } // Get value $primary: map-get($theme-colors, "primary"); // Merge (config + defaults) $final-config: map-merge($defaults, $user-config); ``` ### Rules Maps & Lists - **Maps for related values** — colors, breakpoints, shadows, z-indices - **`map-merge` for config** — user overrides defaults - **`@each` for generation** — DRY component variants --- ## 11. Built-in Modules (Essential) ```scss @use "sass:color"; @use "sass:map"; @use "sass:math"; @use "sass:string"; @use "sass:list"; @use "sass:selector"; @use "sass:meta"; ``` ### Common patterns ```scss // Color palette generation @use "sass:color"; $base: #0066cc; $palette: ( "50": color.scale($base, $lightness: 40%), "100": color.scale($base, $lightness: 30%), "500": $base, "900": color.scale($base, $lightness: -30%), ); // Math helpers @use "sass:math"; $cols: 12; $gutter: 1.5rem; $col-width: math.div(100% - ($gutter * ($cols - 1)), $cols); ``` --- ## 12. Project Architecture (7-1 Pattern) ```text styles/ ├── main.scss # Entry point ├── abstracts/ │ ├── _index.scss # @forward all │ ├── _variables.scss # Tokens │ ├── _mixins.scss # Reusable patterns │ └── _functions.scss # Helpers ├── base/ │ ├── _reset.scss # Normalize/Reset │ ├── _typography.scss # Base type styles │ └── _global.scss # html, body, * ├── components/ │ ├── _index.scss │ ├── _button.scss │ ├── _card.scss │ └── _form.scss ├── layout/ │ ├── _index.scss │ ├── _header.scss │ ├── _footer.scss │ └── _grid.scss ├── pages/ │ ├── _index.scss │ └── _home.scss ├── themes/ │ ├── _index.scss │ └── _dark.scss └── vendors/ └── _bootstrap.scss # @use bootstrap with config ``` ### main.scss ```scss // 1. Abstracts (tokens, mixins, functions) @use "abstracts" as *; // 2. Vendors (3rd party with config) @use "vendors/bootstrap" as bs; // 3. Base (global styles) @use "base/reset"; @use "base/typography"; @use "base/global"; // 4. Layout (macro structure) @use "layout/header"; @use "layout/footer"; @use "layout/grid"; // 5. Components (micro UI) @use "components/button"; @use "components/card"; @use "components/form"; // 6. Pages (specific overrides) @use "pages/home"; // 7. Themes (last — overrides) @use "themes/dark"; ``` ### Rules Architecture - **Order matters** — abstracts → vendors → base → layout → components → pages → themes - **One `@use` per partial** — clear dependency graph - **Themes last** — override variables for dark mode, brand variants --- ## 13. Framework Integration ### Vite ```bash pnpm add -D sass ``` ```ts // vite.config.ts import { defineConfig } from "vite"; export default defineConfig({ css: { preprocessorOptions: { scss: { api: "modern-compiler", // Dart Sass modern API silenceDeprecations: ["import", "global-builtin"], }, }, }, }); ``` ### Astro ```bash pnpm astro add sass # or pnpm add -D sass ``` ```astro ``` > **Vite/Astro config details**: see `vite` and `astro` skills. --- ## 14. Methodology Before using ANY Sass feature/pattern not documented in this skill: 1. **MCP Context7** (priority): `context7_resolve-library-id` + `context7_query-docs` for Sass. 2. **Official docs**: sass-lang.com — verify current syntax + modules. 3. **Project config**: `styles/main.scss`, `vite.config.ts`, `package.json` — verify against actual setup. 4. **HARD RULE**: If not in this skill AND cannot be verified against 2 authoritative sources → DO NOT USE IT. Document as assumption or risk in report to orchestrator. --- ## 15. Prohibitions - ❌ Do not use `@import` — use `@use` / `@forward` (modules) - ❌ Do not use indented syntax (`.sass`) — SCSS only - ❌ Do not use `@extend` / placeholders (`%`) — use mixins - ❌ Do not nest deeper than 3 levels - ❌ Do not use global variables without `!default` - ❌ Do not use `!global` flag — use module system - ❌ Do not duplicate CSS values — use variables/maps - ❌ Do not commit compiled CSS — build in CI --- ## 16. References > **Note:** For CSS conventions, see [CSS](../css/SKILL.md) > **Note:** For Vite integration, see [Vite](../vite/SKILL.md) > **Note:** For Astro integration, see > [Astro](../astro/SKILL.md) --- Last updated: 2026-08