Sass 速查表

// SCSS syntax ($var)
$primary-color: #3498db;
$font-stack: -apple-system, sans-serif;

body {
  font-family: $font-stack;
  color: $primary-color;

  a {
    color: lighten($primary-color, 20%);

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

// SCSS (.scss) - uses braces and semicolons
.box {
  width: 100px;
  height: 100px;
}

// Sass (.sass) - indentation-based, no braces/semicolons
.box
  width: 100px
  height: 100px

// Both compile to the same CSS
// .box { width: 100px; height: 100px; }

// Single-line comment - NOT compiled to CSS
/* Multi-line comment - compiled to CSS */
/*! Important comment - always kept even in compressed mode */

// Silent comment for developers
$base-font: 16px;

/*! Keep this copyright notice */
body { font-size: $base-font; }

// Compile a single file
// $ sass input.scss output.css

// Watch for changes
// $ sass --watch input.scss:output.css

// Watch a directory
// $ sass --watch scss/:css/

// Compressed output
// $ sass --style=compressed input.scss output.css

// Four output styles: expanded, nested, compact, compressed
$width: 100px;
.box { width: $width; }

// Sass adds programming features to CSS:
// 1. Variables ($var)
// 2. Nesting
// 3. Mixins (@mixin / @include)
// 4. Inheritance (@extend)
// 5. Functions (@function)
// 6. Control directives (@if, @for, @each, @while)
// 7. Partials & Modules (@use, @forward)

// These features help keep stylesheets DRY and maintainable.
$radius: 4px;
.card { border-radius: $radius; }

$color: #333;          // global scope
$padding: 10px;         // global

.block {
  $local-color: #fff;   // local to .block
  color: $local-color;
  padding: $padding;    // can read globals
}

// $local-color is NOT available here
// .other { color: $local-color; } // ERROR

// Only assign if the variable is not already defined
$base-color: #333 !default;
$base-color: #fff; // this wins (already? no - assigned above first)

// Useful in libraries/partials for user overrides
// _theme.scss
$primary: blue !default;
.button { background: $primary; }

// User config BEFORE importing
// $primary: red;
// @use 'theme';  -> button is red

$count: 0;

@for $i from 1 through 3 {
  $count: $count + $i !global;
}

// $count is now 6 (1+2+3)
.total { content: "#{$count}"; }

// Without !global, the assignment inside @for
// would create a local variable instead

// Sass has 7 data types:
$number:  16px;              // number (with optional unit)
$string:  "Helvetica";       // string (quoted or unquoted)
$color:   #3498db;           // color
$boolean: true;              // boolean (true/false)
$null:    null;              // null (no value)
$list:    10px 20px 30px;    // list (space or comma separated)
$map:     (key: value);      // map (key-value pairs)

// Type checking
type-of($number)  // number
type-of($list)    // list
type-of($map)     // map

$name: "user";
$version: 2;

// Use #{} to insert variables into selectors and strings
.#{$name}-avatar { background: url("/img/#{$name}.png"); }

// In property names and values
.icon-#{$name} {
  content: "v#{$version}";
}

// Interpolation in @media and @include
@media (max-width: #{$version * 100}px) {
  body { font-size: 14px; }
}

// SCSS nesting mirrors HTML structure
.nav {
  background: #333;

  ul {
    list-style: none;
    margin: 0;

    li {
      display: inline-block;
    }
  }

  a {
    color: white;
    text-decoration: none;
  }
}

// Compiles to: .nav {...} .nav ul {...} .nav ul li {...} .nav a {...}

// AVOID: overly deep nesting
.header {
  .nav {
    > ul {
      li {
        a {
          span {  // 5 levels deep!
            color: red;
          }
        }
      }
    }
  }
}

// Compiles to: .header .nav > ul li a span
// Too specific - hard to override, slow to match

// BETTER: flatten with classes
.header-nav-link-text { color: red; }

.icon {
  // Shorthand for font-family, font-size, font-weight...
  font: {
    family: "Arial";
    size: 14px;
    weight: bold;
  }

  // border-top, border-right, etc.
  border: {
    top: 1px solid #ccc;
    bottom: 2px dashed #999;
  }
}

// Compiles to: font-family, font-size, font-weight, border-top, border-bottom

.container {
  width: 100%;

  // Media query nested inside the rule
  @media (min-width: 768px) {
    width: 720px;
  }

  @media (min-width: 1024px) {
    width: 960px;
  }
}

// Compiles to:
// .container { width: 100%; }
// @media (min-width: 768px) { .container { width: 720px; } }
// @media (min-width: 1024px) { .container { width: 960px; } }

.btn {
  // Comma creates a selector list
  .icon,
  .label {
    color: white;
  }
}

// Compiles to:
// .btn .icon, .btn .label { color: white; }

// Nesting a list with &
.card,
.panel {
  &.active { border-color: blue; }
}

// .card.active, .panel.active { border-color: blue; }

.button {
  background: blue;
  color: white;

  // & refers to the parent (.button)
  &:hover {
    background: darkblue;
  }

  &:focus {
    outline: 2px solid blue;
  }

  &::after {
    content: "→";
  }
}

// Compiles to: .button, .button:hover, .button:focus, .button::after

// BEM methodology with parent selector
.card {
  background: white;

  &__title {       // .card__title
    font-size: 18px;
  }

  &__body {        // .card__body
    padding: 16px;
  }

  &--featured {    // .card--featured
    border-color: gold;
  }

  &--featured &__title {  // .card--featured .card__title
    color: gold;
  }
}

.button {
  background: blue;

  // Append suffix to parent
  &-primary { background: darkblue; }    // .button-primary
  &-secondary { background: gray; }      // .button-secondary
  &-danger { background: red; }          // .button-danger

  // Combining with state
  &-primary.is-active { font-weight: bold; }
}

// Generates: .button, .button-primary, .button-secondary, .button-danger

.modal {
  // & at the end - parent as descendant
  .dark-theme & {
    background: #222;
    color: #eee;
  }

  .sidebar & {
    width: 200px;
  }
}

// Compiles to:
// .dark-theme .modal { background: #222; color: #eee; }
// .sidebar .modal { width: 200px; }

// Useful when parent is styled differently in a context

.button {
  // Multiple & references in one selector
  & + & {              // .button + .button (adjacent sibling)
    margin-left: 8px;
  }

  & ~ & {              // .button ~ .button (general sibling)
    margin-top: 4px;
  }

  &.active &__icon {   // .button.active .button__icon
    color: white;
  }

  .parent &.is-open &__content {
    display: block;
  }
}

// _variables.scss - partial file (underscore prefix)
$primary: #3498db;
$secondary: #2ecc71;
$font-base: 16px;

// _buttons.scss
.button {
  background: $primary;
  padding: $font-base / 2;
}

// Partials are NOT compiled to their own CSS file.
// The underscore tells Sass this is a partial.
// Import them into a main file:
// main.scss:  @use 'variables'; @use 'buttons';

// Common partial naming patterns:
// _variables.scss   - variables
// _mixins.scss      - mixins
// _functions.scss   - functions
// _reset.scss       - CSS reset
// _base.scss        - base styles
// _typography.scss  - typography
// _buttons.scss     - button component
// _header.scss      - header component
// _footer.scss      - footer component
// _mediaqueries.scss - media queries

// Import without the underscore or extension:
// @use 'variables';
// @use 'mixins';

// 7-1 architecture: 7 folders, 1 main file
// sass/
//   abstracts/   - variables, functions, mixins
//   base/        - reset, typography, base styles
//   components/  - buttons, cards, nav
//   layout/      - header, footer, grid
//   pages/       - home, about specific styles
//   themes/      - theme definitions
//   vendors/     - third-party
//   main.scss    - imports everything

// main.scss
// @use 'abstracts/variables';
// @use 'base/reset';
// @use 'components/buttons';
// @use 'layout/header';

// sass/components/_index.scss
// Forward all component partials from one entry point
@forward 'buttons';
@forward 'cards';
@forward 'nav';
@forward 'modal';

// Now in main.scss, one line imports everything:
// @use 'components';
// (resolves to components/_index.scss)

// This keeps the main file clean and lets
// you reorganize partials without touching main.scss

// 1. One concern per partial
// _buttons.scss  -> only buttons
// _forms.scss    -> only forms

// 2. Keep partials small and focused
// (50-200 lines is a good target)

// 3. Use @use (not @import) for explicit dependencies
// _card.scss
@use '../abstracts/variables' as *;
@use '../abstracts/mixins' as *;

.card {
  background: $white;
  @include card-shadow;
}

// 4. Avoid circular dependencies

// @import - the OLD way (deprecated in Sass 1.80+)
@import 'variables';
@import 'mixins';
@import 'buttons';

// Problems with @import:
// 1. Globals leak across files (no namespacing)
// 2. Each @import of the same file runs it again
// 3. No way to make members private
// 4. Extends and mixins can conflict

// Use @use instead (the modern module system)
$primary: blue;

// _variables.scss
$primary: #3498db;
$radius: 4px;

// main.scss - @use creates a namespace (filename by default)
@use 'variables';

.button {
  // Access via namespace::member
  background: variables.$primary;
  border-radius: variables.$radius;
}

// The namespace prevents naming collisions
// and makes dependencies explicit

// _variables.scss
$primary: blue;
$secondary: green;

// Rename the namespace with 'as'
@use 'variables' as v;

.btn {
  background: v.$primary;
  color: v.$secondary;
}

// Or remove the namespace entirely (use with caution)
@use 'variables' as *;

.card {
  background: $primary;  // direct access, no prefix
}

// 'as *' can cause collisions - prefer named namespaces

// _theme.scss
$primary: blue !default;
$radius: 4px !default;

.button {
  background: $primary;
  border-radius: $radius;
}

// main.scss - configure variables on import
@use 'theme' with (
  $primary: red,
  $radius: 8px
);

// The 'with' clause sets variables marked !default
// This is how libraries are configured by users

// @import (old) - global, no namespace
@import 'variables';
.button { background: $primary; }  // global $primary

// @use (new) - namespaced, loaded once
@use 'variables';
.button { background: variables.$primary; }

// Key differences:
// @import: global scope, runs multiple times, no privacy
// @use:    namespaced, runs once, supports private (-prefix)

// _mixins.scss with a private member
@mixin -internal { /* private - not exposed */ }
@mixin public { @include -internal; }

// @use only exposes non-private (no dash prefix) members

// Define a mixin with @mixin
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

@mixin card-shadow {
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

// Use with @include
.hero {
  @include center;
  height: 200px;
}

.modal {
  @include center;
  @include card-shadow;
}

@mixin button($bg, $color) {
  background: $bg;
  color: $color;
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
}

// Pass arguments by position
.btn-primary { @include button(blue, white); }
.btn-danger { @include button(red, white); }

// Pass arguments by name (clearer, order-independent)
.btn-info { @include button($color: white, $bg: teal); }

@mixin border($width: 1px, $style: solid, $color: #ccc) {
  border: $width $style $color;
}

// Use all defaults
.box { @include border; }
// border: 1px solid #ccc;

// Override one - use named args to skip earlier ones
.card { @include border($color: blue); }
// border: 1px solid blue;

// Override by position
.banner { @include border(2px, dashed); }
// border: 2px dashed #ccc;

// @content lets you pass a block of styles to a mixin
@mixin respond-to($breakpoint) {
  @media (min-width: $breakpoint) {
    @content;  // injected styles go here
  }
}

.sidebar {
  width: 100%;

  @include respond-to(768px) {
    width: 250px;  // this block replaces @content
    float: left;
  }
}

// Compiles to:
// .sidebar { width: 100%; }
// @media (min-width: 768px) { .sidebar { width: 250px; float: left; } }

// ... captures multiple args into a list (or expands a list)
@mixin box-shadow($shadows...) {
  box-shadow: $shadows;
}

.card { @include box-shadow(0 1px 2px black, 0 4px 8px gray); }
// box-shadow: 0 1px 2px black, 0 4px 8px gray;

// Expanding a list into arguments
$shadows: 0 1px 2px black, 0 4px 8px gray;
.modal { @include box-shadow($shadows...); }

// Also works for @include with maps as keyword args
@mixin theme($colors) { /* ... */ }
@include theme(("bg": red, "fg": white)...);

.message {
  padding: 10px;
  border: 1px solid #ccc;
  border-radius: 4px;
}

// .success inherits all .message styles
.success {
  @extend .message;
  background: #d4edda;
  border-color: #c3e6cb;
}

.error {
  @extend .message;
  background: #f8d7da;
  border-color: #f5c6cb;
}

// Compiles to: .message, .success, .error { padding: 10px; ... }

// You can extend any selector, not just classes
a:hover {
  text-decoration: underline;
}

.link-card:hover {
  @extend a:hover;  // inherits :hover rule
  color: blue;
}

// Extending with compound selectors
.icon {
  display: inline-block;
}

.icon.large {
  font-size: 24px;
}

.icon-x { @extend .icon.large; }  // extends BOTH rules

.base {
  display: block;
  padding: 8px;
}

.intermediate {
  @extend .base;
  background: #eee;
}

.final {
  @extend .intermediate;
  color: red;
}

// .final inherits from .intermediate which inherits from .base
// Compiles to: .base, .intermediate, .final { display: block; padding: 8px; }
//              .intermediate, .final { background: #eee; }
//              .final { color: red; }

// !optional prevents errors if the selector doesn't exist
.fluent {
  @extend .nonexistent !optional;  // no error, just skipped
  color: blue;
}

// Without !optional, extending a missing selector throws:
// ".nonexistent failed to @extend"
// Use !optional when the extension target may or may not exist
// (e.g., optional theme classes from a third-party library)

// @extend - shares one rule, groups selectors
.btn { padding: 8px; }
.primary { @extend .btn; background: blue; }
// -> .btn, .primary { padding: 8px; }

// @mixin - duplicates declarations each use
@mixin btn { padding: 8px; }
.primary { @include btn; background: blue; }
// -> .primary { padding: 8px; background: blue; }

// When to use which:
// @extend: share base styles semantically (DRY selectors)
// @mixin: configurable repeated declarations (with args)
// Avoid @extend across module boundaries (can cause side effects)

// %placeholder selectors are NOT output in CSS
// They only appear when @extended
%base-message {
  padding: 10px;
  border-radius: 4px;
}

.success { @extend %base-message; background: green; }
.error { @extend %base-message; background: red; }

// Compiles to (notice %base-message is gone):
// .success, .error { padding: 10px; border-radius: 4px; }
// .success { background: green; }
// .error { background: red; }

// Class as extend target - the class IS output
.message { padding: 10px; }  // appears in CSS even if unused
.success { @extend .message; }

// Placeholder as extend target - NOT output
%message { padding: 10px; }  // never appears in CSS
.success { @extend %message; }

// Result is identical for .success, but the placeholder
// version doesn't pollute the CSS with an unused .message rule.
// Use placeholders for internal/inheritance-only base styles.

%card-base {
  background: white;
  border: 1px solid #eee;
  border-radius: 8px;
  padding: 16px;
}

%card-shadow {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

// Combine multiple placeholders
.featured-card {
  @extend %card-base;
  @extend %card-shadow;
  border-color: gold;
}

%button { padding: 8px 16px; border: none; cursor: pointer; }
%rounded { border-radius: 4px; }
%shadow { box-shadow: 0 1px 3px rgba(0,0,0,0.2); }

// Many components share the same placeholders
.btn-primary { @extend %button; @extend %rounded; @extend %shadow; background: blue; }
.btn-secondary { @extend %button; @extend %rounded; background: gray; }
.btn-ghost { @extend %button; background: transparent; }

// Sass deduplicates: %button's rule is shared across all three

// 1. Design system primitives
%abs-center {
  position: absolute;
  top: 50%; left: 50%;
  transform: translate(-50%, -50%);
}

// 2. Clearfix
%clearfix::after {
  content: "";
  display: table;
  clear: both;
}

// 3. Visually hidden (accessibility)
%visually-hidden {
  position: absolute;
  width: 1px; height: 1px;
  overflow: hidden;
  clip: rect(0 0 0 0);
}

.modal { @extend %abs-center; }
.container { @extend %clearfix; }
.sr-only { @extend %visually-hidden; }

// @function defines a function that returns a value
@function rem($px) {
  $base: 16px;
  @return ($px / $base) * 1rem;
}

// Use it like a CSS function
body { font-size: rem(16); }      // 1rem
h1 { font-size: rem(32); }        // 2rem
.small { font-size: rem(12); }    // 0.75rem

// Functions return values; mixins output CSS rules

@function spacing($factor: 1, $base: 8px) {
  @return $base * $factor;
}

// Use defaults
.card { padding: spacing(); }       // 8px
.card-lg { padding: spacing(2); }   // 16px

// Override by name
.section { padding: spacing($base: 10px); }  // 10px
.hero { padding: spacing(3, 10px); }         // 30px

// Variable arguments work too
@function max-of($nums...) {
  @return ...; // implement with reduce
}

// Color functions
lighten(#000, 50%)       // gray
rgba(#fff, 0.5)          // semi-transparent white
mix(red, blue)           // purple

// Math functions
percentage(0.5)          // 50%
round(3.6)               // 4
min(10px, 20px)          // 10px

// String functions
to-upper-case("abc")     // "ABC"
str-length("hello")      // 5

// List/Map functions
length(1 2 3)            // 3
map-get(("a": 1), "a")   // 1

// Modern Sass uses modules: @use 'sass:math'; math.div(10, 2)

// Convert px to em relative to a context
@function em($px, $context: 16px) {
  @return ($px / $context) * 1em;
}

// Generate a z-index from a scale map
$z-indexes: (
  "base": 0,
  "dropdown": 100,
  "modal": 200,
  "toast": 300,
);
@function z($name) {
  @return map-get($z-indexes, $name);
}

// Usage
body { font-size: em(18px); }              // 1.125em
.modal { z-index: z("modal"); }            // 200
.toast { z-index: z("toast"); }            // 300

// Functions can call themselves (recursion)
@function factorial($n) {
  @if $n <= 1 {
    @return 1;
  } @else {
    @return $n * factorial($n - 1);
  }
}

.power { width: factorial(5) * 1px; }  // 120px

// Fibonacci
@function fib($n) {
  @if $n < 2 { @return $n; }
  @return fib($n - 1) + fib($n - 2);
}

// Note: deep recursion is slow in Sass - use sparingly

@mixin theme($mode) {
  @if $mode == dark {
    background: #222;
    color: #eee;
  } @else if $mode == light {
    background: #fff;
    color: #333;
  } @else {
    background: gray;
    color: black;
  }
}

.dark { @include theme(dark); }
.light { @include theme(light); }
.auto { @include theme(auto); }

// Comparison operators: ==, !=, <, >, <=, >=, and, or, not

// @for $var from <start> through <end>  (inclusive)
@for $i from 1 through 3 {
  .col-#{$i} { width: 100% / $i; }
}
// .col-1 { width: 100%; }  .col-2 { width: 50%; }  .col-3 { width: 33.333%; }

// 'to' is EXCLUSIVE (excludes the end)
@for $i from 1 to 3 {
  .item-#{$i} { order: $i; }
}
// .item-1, .item-2  (no .item-3)

// Use 'through' for inclusive, 'to' for exclusive ranges

// Iterate over a list
$icons: user, home, settings, search;

@each $name in $icons {
  .icon-#{$name} {
    background-image: url("/icons/#{$name}.svg");
  }
}
// .icon-user, .icon-home, .icon-settings, .icon-search

// Multiple values (unpacking)
@each $name, $color in (success green), (error red) {
  .alert-#{$name} { color: $color; }
}

$breakpoints: (
  "sm": 576px,
  "md": 768px,
  "lg": 1024px,
  "xl": 1280px,
);

// Iterate key-value pairs of a map
@each $name, $size in $breakpoints {
  .container-#{$name} {
    max-width: $size;
    margin: 0 auto;
  }
}
// .container-sm, .container-md, .container-lg, .container-xl

// Also destructuring lists of maps for richer config
$buttons: (("primary", blue), ("danger", red));

// @while repeats while a condition is true
$i: 1;
@while $i <= 5 {
  .mt-#{$i} { margin-top: $i * 4px; }
  $i: $i + 1;
}
// .mt-1 { margin-top: 4px; } ... .mt-5 { margin-top: 20px; }

// Unlike @for, you control the increment
// WARNING: always increment/decrement to avoid infinite loops!
$i: 6;
@while $i > 0 {
  .delay-#{$i} { transition-delay: $i * 100ms; }
  $i: $i - 1;
}

// Lists are ordered collections (like arrays)
// Separated by spaces or commas
$sizes: 10px 20px 30px;          // space-separated
$colors: red, green, blue;       // comma-separated
$mixed: (1px 2px) (3px 4px);     // nested lists

// Single value is also a list of length 1
$one: 5px;

// Indexes are 1-based!
$list: a b c;
nth($list, 1);   // a  (NOT 0-indexed)
nth($list, -1);  // c  (negative = from end)
length($list);   // 3

$list: a b c;

// Access
length($list);          // 3
nth($list, 2);          // b
index($list, b);        // 2 (position of b, or null)

// Modify (return NEW list - lists are immutable)
append($list, d);       // a b c d
join(a b, c d);         // a b c d
join((a b), (c d), comma); // a, b, c, d

// Insert
insert-nth($list, 2, x);   // a x b c

// Misc
zip(1 2, a b);          // (1 a) (2 b) - pairs elements

// Maps are key-value pairs (like objects/dictionaries)
$colors: (
  "primary": #3498db,
  "secondary": #2ecc71,
  "danger": #e74c3c,
  "warning": #f39c12,
);

// Access values
map-get($colors, "primary");      // #3498db

// Check existence
map-has-key($colors, "success");  // false

// Keys must be unique; values can be any type (even nested maps)
$breakpoints: (
  "mobile": (max: 767px),
  "desktop": (min: 768px),
);

$colors: ("a": 1, "b": 2);

// Access
map-get($colors, "a");          // 1
map-has-key($colors, "c");      // false

// Keys & values as lists
map-keys($colors);              // ("a", "b")
map-values($colors);            // (1, 2)

// Merge (combines two maps; second wins on conflicts)
$base: ("x": 1, "y": 2);
$override: ("y": 99, "z": 3);
map-merge($base, $override);    // ("x": 1, "y": 99, "z": 3)

// Remove keys
map-remove($colors, "a");       // ("b": 2)

$grid: (
  "sm": 576px,
  "md": 768px,
  "lg": 1024px,
);

// @each destructures map into key+value
@each $name, $size in $grid {
  @media (min-width: $size) {
    .container-#{$name} { max-width: $size; }
  }
}

// Nested destructuring with lists of lists
$config: (("primary", blue, white), ("danger", red, white));
@each $name, $bg, $fg in $config {
  .btn-#{$name} { background: $bg; color: $fg; }
}

$base: #3498db;

.light { background: lighten($base, 20%); }   // lighter blue
.dark  { background: darken($base, 20%); }    // darker blue

// Note: lighten/darken are deprecated in modern Sass
// Prefer sass:color adjust() for clarity:
@use 'sass:color';
.adjusted {
  // same effect, explicit
  background: color.adjust($base, $lightness: 20%);
  border-color: color.adjust($base, $lightness: -20%);
}

$brand: #3498db;

// Add alpha to any color
.semi { background: rgba($brand, 0.5); }    // #3498db at 50%
.fade { background: rgba($brand, 0.1); }    // very transparent

// rgba() also accepts 4 numeric args
.box { background: rgba(52, 152, 219, 0.8); }

// Modern alternative: color.adjust for alpha
@use 'sass:color';
.glass { background: color.adjust($brand, $alpha: -0.5); }

// rgb() and rgba() with space syntax (CSS Color 4)
.modern { background: rgb(52 152 219 / 80%); }

// mix() blends two colors by a weight (default 50%)
$mix: mix(red, blue);          // purple (50/50)
$mix30: mix(red, blue, 30%);   // 30% red, 70% blue (bluer)

// Useful for generating tints and shades
$base: #3498db;
.tint  { background: mix($base, white, 20%); }  // 20% blue, 80% white
.shade { background: mix($base, black, 20%); }  // 20% blue, 80% black

// sass:color module
@use 'sass:color';
.blended { background: color.mix(red, blue, 50%); }

@use 'sass:color';
$base: #3498db;

// adjust: ADDS to channels (absolute change)
.a { background: color.adjust($base, $red: 30, $alpha: -0.3); }

// scale: SCALES channels by % (relative change, stays in range)
.s { background: color.scale($base, $lightness: 50%); }

// change: SETS channels to exact values (replaces)
.c { background: color.change($base, $lightness: 50%, $hue: 0); }

// adjust moves by a delta, scale shrinks/grows toward min/max,
// change overwrites with a fixed value.

@use 'sass:color';
$c: #3498db;

// Read HSL channels
color.hue($c);           // 204deg
color.saturation($c);    // 70%
color.lightness($c);     // 53%

// Derive new colors
.complement { background: color.complement($c); }     // opposite hue
.grayscale  { background: color.grayscale($c); }       // desaturated
.invert     { background: color.invert($c); }          // RGB inverse

// Build from HSL
.from-hsl { background: color.hsl(204, 70%, 53%); }

$base: 16px;

// Sass does math on numbers (with unit handling)
width: 100% - 20px;   // ERROR - incompatible units
width: 100px + 20px;  // 120px
width: 100px * 2;     // 200px
width: 100px / 2;     // 50px (use math.div in modern Sass)
width: (100px / 2);   // 50px (parenthesized = math, not CSS)

// Modern division (the / operator is deprecated for division)
@use 'sass:math';
width: math.div(100px, 2);   // 50px
width: math.div(100, 3);     // 33.333...

$base-font: 16px;

// Convert px to rem
@function rem($px) {
  @return math.div($px, $base-font) * 1rem;
}
h1 { font-size: rem(32px); }   // 2rem

// Convert px to em (relative to context)
@function em($px, $context: 16px) {
  @return math.div($px, $context) * 1em;
}

// Sass does NOT auto-convert between px/em/rem/%
// You must compute the ratio yourself.
// 1in = 96px, 1cm = 37.8px, 1pt = 1.33px (these DO auto-convert)

@use 'sass:math';

// Rounding
math.round(3.6);     // 4
math.ceil(3.1);      // 4
math.floor(3.9);     // 3

// Absolute & bounds
math.abs(-5);        // 5
math.min(10px, 20px);  // 10px
math.max(10px, 20px);  // 20px

// Percentage conversion
math.percentage(0.5);  // 50%  (math.percentage, or global percentage)

// Trig & constants (Sass 1.65+)
math.sin(math.$pi);    // ~0
math.cos(0);           // 1
math.sqrt(16);         // 4

@use 'sass:math';

// Modulo (remainder)
math.unit(10px);     // px
math.compatible(10px, 5px);  // true (can add)
math.is-unitless(5);          // true

// Division MUST use math.div (the / operator is for lists/CSS)
$result: math.div(100, 3);    // 33.333...

// Modulo
$rem: math.mod(10, 3);        // 1

// Generating a grid with modulo
@for $i from 1 through 12 {
  .col-#{$i} { width: math.div($i, 12) * 100%; }
}

// Comparison: ==, !=, <, >, <=, >=
@if $width > 100px { /* ... */ }
@if $count == 3 { /* ... */ }
@if $mode != "dark" { /* ... */ }

// Boolean logic: and, or, not (NOT &&, ||, !)
$enabled: true;
$mobile: false;

@if $enabled and not $mobile {
  .desktop-only { display: block; }
}

@if $mode == "dark" or $mode == "night" {
  background: black;
}

// Use parentheses to group
@if ($a > 1 and $b < 10) or $c == 5 { /* ... */ }

// quote() forces quotes around a string
$unquoted: Helvetica;
$quoted: quote($unquoted);   // "Helvetica"

// unquote() removes quotes
$quoted: "Arial";
$plain: unquote($quoted);    // Arial

// Useful when a string needs to be quoted for output
.url { background: url(quote("/img/x.png")); }
// url("/img/x.png")

// Quoted vs unquoted matters for some CSS values
// Class names and property names are usually unquoted

// Change string case
$upper: to-upper-case("hello");   // "HELLO"
$lower: to-lower-case("WORLD");   // "world"

// Practical: generate uppercase class names
$states: success, warning, error;
@each $s in $states {
  .badge-#{to-upper-case($s)} {
    content: "#{to-upper-case($s)}";
  }
}

// .badge-SUCCESS { content: "SUCCESS"; } etc.

@use 'sass:string';

$str: "Hello, World";

// Length (character count)
string.length($str);    // 12

// Slice (substring) - 1-based, supports negatives
string.slice($str, 1, 5);   // "Hello"
string.slice($str, 8);      // "World"
string.slice($str, -5);     // "World" (from end)

// Index of substring (1-based, or null if not found)
string.index($str, "World");  // 8
string.index($str, "xyz");    // null

// Split is not built-in - use a custom function with index+slice

@use 'sass:string';

// str-insert: insert at position (1-based)
string.insert("Hello", "!", 6);    // "Hello!"
string.insert("World", "Hello ", 1);  // "Hello World"

// Modern Sass (1.55+) has string.replace
string.replace("a-b-c", "-", "_");        // "a_b_c" (replace all)
string.replace("a-b-c", "-", "_", 1);     // "a_b-c" (limit 1)

// Build dynamic strings
$prefix: "icon";
$name: string.insert($prefix, "-user", 100);  // "icon-user"

$prefix: "btn";
$modifier: "primary";

// #{} converts any value to a string and embeds it
.#{$prefix}-#{$modifier} { /* ... */ }   // .btn-primary

// Interpolating numbers, lists, booleans
$count: 3;
.item-#{$count} { order: $count; }       // .item-3 { order: 3; }

// Interpolating in @include and @media
@mixin respond-to($bp) {
  @media (max-width: $bp) { @content; }
}

// Interpolating function calls
.content::after {
  content: "#{to-upper-case('hello')}";
}

.parent {
  color: blue;

  // @at-root jumps out of the nesting
  @at-root .child {
    color: red;
  }
}

// Compiles to (note: .child is NOT nested under .parent):
// .parent { color: blue; }
// .child { color: red; }   <- top-level, not .parent .child

// Useful for defining sibling/related rules inside a block
// without creating a descendant selector.

.component {
  width: 100px;

  // Combine @at-root with & to keep part of the parent
  @at-root .wrapper & {
    background: yellow;
  }
  // -> .wrapper .component { background: yellow; }

  // Useful for context overrides without deep nesting
  @at-root .dark-theme & {
    color: white;
  }
  // -> .dark-theme .component { color: white; }
}

.block {
  // State classes as siblings, not descendants
  @at-root {
    .block--active { border-color: blue; }
    .block--disabled { opacity: 0.5; }
  }

  // Or inline form
  @at-root .block--hidden { display: none; }
}

// Compiles to top-level siblings:
// .block { ... }
// .block--active { border-color: blue; }
// .block--disabled { opacity: 0.5; }
// .block--hidden { display: none; }

// Avoids accidentally generating .block .block--active

.component {
  width: 100%;

  // @at-root lifts media queries to the top level
  @at-root (with: media) {
    @media (min-width: 768px) {
      & { width: 50%; }
    }
  }
  // -> @media (min-width: 768px) { .component { width: 50%; } }
}

// Default @at-root (without: rule) lifts OUT of everything
// @at-root (with: media) keeps the @media context but exits rules
// Useful in complex nested mixins to control scope precisely

.parent {
  @media (min-width: 768px) {
    .child {
      width: 50%;

      // Exit only the rule, keep the @media
      @at-root (without: rule) {
        .sibling { width: 25%; }
      }
      // -> @media (min-width: 768px) { .sibling { width: 25%; } }

      // Exit everything (default)
      @at-root .top { color: red; }
      // -> .top { color: red; }  (no @media, no parent)
    }
  }
}

// @content marks where the included block is injected
@mixin highlighted {
  background: yellow;
  font-weight: bold;

  @content;  // the block passed to @include goes here
}

.title {
  @include highlighted {
    color: red;       // injected where @content was
    font-size: 20px;
  }
}

// Compiles to:
// .title { background: yellow; font-weight: bold; color: red; font-size: 20px; }

// Pass values back to the included block (Sass 3.3+)
@mixin each-breakpoint {
  $breakpoints: (sm: 576px, md: 768px, lg: 1024px);

  @each $name, $size in $breakpoints {
    @media (min-width: $size) {
      @content ($name, $size);
    }
  }
}

// Receive via #{...} - actually use the block like a function
@include each-breakpoint using ($name, $size) {
  .container-#{$name} { max-width: $size; }
}

// Classic responsive mixin pattern
@mixin respond-to($breakpoint) {
  @if $breakpoint == phone {
    @media (max-width: 600px) { @content; }
  } @else if $breakpoint == tablet {
    @media (min-width: 601px) and (max-width: 900px) { @content; }
  } @else if $breakpoint == desktop {
    @media (min-width: 901px) { @content; }
  }
}

.sidebar {
  width: 300px;

  @include respond-to(phone) {
    width: 100%;
    float: none;
  }

  @include respond-to(desktop) {
    width: 350px;
  }
}

// Wrapper for @supports (feature queries)
@mixin supports-flex { @supports (display: flex) { @content; } }

// Keyframes generator
@mixin keyframes($name) {
  @keyframes #{$name} { @content; }
}

@include keyframes(fade-in) {
  from { opacity: 0; }
  to   { opacity: 1; }
}

// Modifier generator
@mixin modifier($name) {
  &--#{$name} { @content; }
}
.button {
  @include modifier(primary) { background: blue; }
  @include modifier(danger) { background: red; }
}

// 1. Context wrappers (@media, @supports, @keyframes)
@mixin mobile { @media (max-width: 767px) { @content; } }

// 2. Reset/normalize hooks
@mixin base-styles {
  box-sizing: border-box;
  margin: 0;
  @content;  // allow components to add more
}

// 3. Debugging/profiling wrappers
@mixin timed {
  $start: systime();
  @content;
  // log elapsed...
}

// 4. Conditional output
@mixin if-dark($is-dark) {
  @if $is-dark { @content; }
}

// @use is the modern module system (replaces @import)
// Key improvements:
// 1. Members are namespaced (no global pollution)
// 2. Modules load ONCE (cached, no duplicate execution)
// 3. Privacy: members starting with - or _ are private
// 4. Explicit configuration with 'with'

// _shapes.scss
$radius: 4px;
@mixin rounded { border-radius: $radius; }
@mixin -internal { /* private */ }   // not exposed

// app.scss
@use 'shapes';          // namespace: shapes
@use 'shapes' as s;     // namespace: s
@use 'shapes' as *;     // no namespace (global)

.card { @include shapes.rounded; }   // via namespace

// @forward re-exports members from another module
// Useful for building index/barrel files

// sass/abstracts/_index.scss
@forward 'variables';    // exposes _variables.scss members
@forward 'functions';
@forward 'mixins';

// Now consumers can import the whole folder at once:
// app.scss
@use 'abstracts' as *;   // gets variables + functions + mixins

// @forward can rename or hide members
@forward 'buttons' hide button-styles;
@forward 'forms' as form-*;  // prefix all members with 'form-'

// _math-helpers.scss
@function -internal-double($n) {
  @return $n * 2;
}

@function public-times-two($n) {
  @return -internal-double($n);  // OK - same file
}

// Public function usable via @use
@function scale($n, $factor: 2) {
  @return -internal-double($n) * $factor;
}

// app.scss
@use 'math-helpers';
.val { width: math-helpers.scale(10); }      // OK
// .val { width: math-helpers.-internal-double(10); }  // ERROR - private

// _theme.scss
$primary: blue !default;
$radius: 4px !default;

@mixin button {
  background: $primary;
  border-radius: $radius;
}

// app.scss - configure on @use
@use 'theme' with (
  $primary: #ff6600,
  $radius: 8px,
);

.btn { @include theme.button; }
// background: #ff6600; border-radius: 8px;

// 'with' only works for variables marked !default in the module.
// Configuration must happen at the FIRST @use of that module.

// 1. Always use @use, never @import (deprecated)
// 2. Use explicit namespaces for clarity
@use 'sass:math';      // built-in module namespace: math
@use 'variables' as v; // short custom namespace

// 3. Use @forward in _index.scss barrel files
// components/_index.scss
@forward 'buttons';
@forward 'cards';

// 4. Keep members private with - prefix
@function -helper() { @return ...; }

// 5. Configure libraries with 'with', set !default on library vars
$brand: blue !default;

// 6. Use built-in modules: sass:math, sass:color, sass:string,
//    sass:list, sass:map, sass:meta, sass:selector, sass:css

// @debug prints a message to the console during compilation
$base: 16px;
$size: 24px;

@debug "Calculating size...";
@debug "base is #{$base}, size is #{$size}";
@debug "ratio: " #{math.div($size, $base)};

// Console output during compile:
// _file.scss:5 DEBUG: Calculating size...
// _file.scss:6 DEBUG: base is 16px, size is 24px

// @debug does NOT stop compilation - just logs
// Use it to trace values while developing

// @warn prints a warning to the console (does NOT stop compilation)
@mixin deprecated-mixin {
  @warn "deprecated-mixin is deprecated; use new-mixin instead.";
  /* ... styles ... */
}

// Useful for deprecation notices, potential issues
@warn "Variable $primary is not set, falling back to default.";

// With stack trace for locating the call site
@warn "Invalid value: #{$value}" {
  // optional stack trace via meta.module-functions
}

// @warn is non-fatal - compilation continues.

// @error stops compilation with an error message
@function divide($a, $b) {
  @if $b == 0 {
    @error "Cannot divide by zero: divide(#{$a}, #{$b})";
  }
  @return math.div($a, $b);
}

// In a mixin validating arguments
@mixin set-font-size($size) {
  @if not $size {
    @error "set-font-size requires a non-null $size, got #{$size}";
  }
  font-size: $size;
}

// @error halts the build - use for invalid inputs
// that would produce broken CSS.

@use 'sass:meta';

// Inspect values
meta.type-of(10px);          // number
meta.type-of("hi");          // string
meta.type-of((a: 1));        // map
meta.inspect((a: 1, b: 2));  // (a: 1, b: 2) - readable representation

// Variable existence (within current scope)
meta.variable-exists("base");    // true if $base exists
meta.global-variable-exists("primary");

// Mixin/function existence
meta.mixin-exists("my-mixin");
meta.function-exists("my-func");

// Feature queries
meta.feature-exists("at-error");  // true

// Get a function reference (for higher-order use)
$fn: meta.get-function("lighten");

@use 'sass:meta';
@use 'sass:math';

// type-of: get the type of any value
$value: 16px;
type-of($value);          // number
type-of("hello");         // string
type-of(#fff);            // color
type-of(true);            // bool
type-of(null);            // null
type-of(1 2 3);           // list
type-of((a: 1));          // map

// inspect: readable debug output of complex values
$map: (primary: blue, secondary: green);
debug: inspect($map);  // (primary: blue, secondary: green)

// unit / unitless for numbers
math.unit(16px);         // px
math.is-unitless(16);    // true

// Combine with @debug for tracing
@debug "got: #{inspect($map)}";

// SCSS - Sassy CSS
// Uses braces {} and semicolons ;
// Superset of CSS - all CSS is valid SCSS

$primary: #3498db;

.button {
  background: $primary;

  &:hover {
    background: darken($primary, 10%);
  }

  .icon {
    width: 16px;
    height: 16px;
  }
}

// Pros: familiar to CSS devs, easy migration, widely adopted

// Sass - indented syntax
// NO braces, NO semicolons - uses indentation only
// Removes CSS punctuation for a cleaner look

$primary: #3498db

.button
  background: $primary

  &:hover
    background: darken($primary, 10%)

  .icon
    width: 16px
    height: 16px

// Pros: less typing, cleaner visually
// Cons: can't paste CSS directly, less popular, error-prone indentation

// Convert SCSS to Sass (and vice versa) with the sass CLI:
// $ sass-convert style.scss style.sass
// $ sass-convert style.sass style.scss

// Bulk convert a folder:
// $ sass-convert --recursive --from scss --to sass scss/ sass/
// $ sass-convert --recursive --from sass --to scss sass/ scss/

// Key syntax differences:
// 1. SCSS uses { } and ;  |  Sass uses indentation
// 2. SCSS: @include mixin()  |  Sass: +mixin()
// 3. SCSS: @mixin name {}    |  Sass: =name
// 4. SCSS: @import "x"       |  Sass: same
// 5. Multi-line: SCSS needs ; | Sass just newlines

// Use SCSS (.scss) when:
// - Starting a new project (most common choice)
// - Migrating an existing CSS codebase (CSS is valid SCSS)
// - Working on a team (most developers know SCSS)
// - Using CSS frameworks/libraries (they're usually SCSS)

// Use Sass (.sass) when:
// - You prefer minimal punctuation / Python-like syntax
// - Writing from scratch with no CSS to migrate
// - Personal preference for cleaner-looking source

// Both produce identical CSS. The choice is stylistic.
// IMPORTANT: don't mix .scss and .sass in the same project.

// 1. Division: / is deprecated for math, use math.div()
@use 'sass:math';
width: math.div(100px, 2);   // CORRECT
// width: 100px / 2;          // DEPRECATED (may be CSS list separator)

// 2. @import is deprecated - use @use/@forward
@use 'variables';             // CORRECT
// @import 'variables';        // DEPRECATED

// 3. lighten()/darken() deprecated - use color.adjust
@use 'sass:color';
color.adjust($c, $lightness: 10%);   // CORRECT
// lighten($c, 10%);                  // DEPRECATED

// 4. Global color functions deprecated - use sass:color module
color.mix(red, blue);          // CORRECT (via @use 'sass:color')
// mix(red, blue);              // DEPRECATED global function