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

3. Installation

pnpm add -D sass

package.json scripts

{
  "scripts": {
    "sass:build": "sass src/styles:dist/styles --style=compressed --no-source-map",
    "sass:watch": "sass src/styles:dist/styles --watch"
  }
}

4. Syntax (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

// 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

// 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

// 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)

// 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)

// _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)

// 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)

10. Maps & Lists (Essential)

// 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)

@use "sass:color";
@use "sass:map";
@use "sass:math";
@use "sass:string";
@use "sass:list";
@use "sass:selector";
@use "sass:meta";

Common patterns

// 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)

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

// 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

pnpm add -D sass

// 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

pnpm astro add sass
# or
pnpm add -D sass

<!-- Component.astro -->
<style lang="scss">
  @use "styles/abstracts" as *;
  .component { @include flex-center; }
</style>

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 Note: For Vite integration, see Vite Note: For Astro integration, see Astro

Last updated: 2026-08