Sass Best Practices
You are an expert in Sass (the indented syntax), CSS architecture, and maintainable stylesheet development.
Key Principles Write clean, readable Sass using the indented syntax (whitespace-sensitive) Leverage Sass features to create DRY, modular stylesheets Maintain consistent indentation as it defines code structure Prioritize simplicity and clarity in style organization Sass vs SCSS
Sass uses the original indented syntax:
No curly braces {} No semicolons ; Indentation defines nesting File extension: .sass // Sass (indented syntax) .button display: inline-flex padding: 8px 16px background: #3498db
&:hover background: darken(#3498db, 10%)
// SCSS syntax (for comparison) .button { display: inline-flex; padding: 8px 16px; background: #3498db;
&:hover { background: darken(#3498db, 10%); } }
File Organization Project Structure sass/ ├── abstracts/ │ ├── _variables.sass │ ├── _functions.sass │ ├── _mixins.sass │ └── _placeholders.sass ├── base/ │ ├── _reset.sass │ ├── _typography.sass │ └── _base.sass ├── components/ │ ├── _buttons.sass │ ├── _cards.sass │ └── _forms.sass ├── layout/ │ ├── _header.sass │ ├── _footer.sass │ └── _grid.sass ├── pages/ │ └── _home.sass ├── themes/ │ └── _default.sass ├── vendors/ │ └── _normalize.sass └── main.sass
Main Manifest // main.sass @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/footer'
@use 'components/buttons' @use 'components/cards' @use 'components/forms'
@use 'pages/home'
@use 'themes/default'
Variables Naming and Organization // _variables.sass
// 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 Scale $spacing-unit: 8px $spacing-xs: $spacing-unit * 0.5 $spacing-sm: $spacing-unit $spacing-md: $spacing-unit * 2 $spacing-lg: $spacing-unit * 3 $spacing-xl: $spacing-unit * 4 $spacing-xxl: $spacing-unit * 6
// Breakpoints $breakpoint-sm: 576px $breakpoint-md: 768px $breakpoint-lg: 992px $breakpoint-xl: 1200px
// Z-index Scale $z-index-dropdown: 1000 $z-index-sticky: 1020 $z-index-fixed: 1030 $z-index-modal: 1050 $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
// 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)
Using Maps // Define maps for grouped values $colors: ("primary": #3498db, "secondary": #2ecc71, "danger": #e74c3c, "warning": #f39c12, "success": #27ae60)
$breakpoints: ("sm": 576px, "md": 768px, "lg": 992px, "xl": 1200px)
// Access values .element color: map-get($colors, "primary")
Mixins Responsive Design // _mixins.sass
=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%
+respond-to("md") width: 50%
+respond-to("lg") width: 33.333%
Flexbox Utilities =flex-center display: flex align-items: center justify-content: center
=flex-between display: flex align-items: center justify-content: space-between
=flex-column display: flex flex-direction: column
// Usage .container +flex-center min-height: 100vh
Typography =font-size($size, $line-height: null) font-size: $size @if $line-height line-height: $line-height
=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
// Usage .title +font-size(2rem, 1.2)
.description +truncate(3)
Accessibility =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
=focus-visible &:focus-visible outline: 2px solid $color-primary outline-offset: 2px
// Usage .sr-only +visually-hidden
.interactive +focus-visible
Button Styles =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
=button-variant($bg-color, $text-color: white) +button-base background: $bg-color color: $text-color
&:hover:not(:disabled) background: darken($bg-color, 10%)
&:active:not(:disabled) background: darken($bg-color, 15%)
// Usage .btn-primary +button-variant($color-primary)
.btn-secondary +button-variant($color-secondary)
.btn-danger +button-variant($color-error)
BEM Naming Convention // Block .card 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 Guidelines Keep Nesting Shallow // BAD: Too deep .nav .nav-list .nav-item .nav-link .nav-icon // 5 levels - avoid this
// GOOD: Flat BEM structure .nav display: flex
.nav__list display: flex list-style: none margin: 0 padding: 0
.nav__item margin: 0 $spacing-sm
.nav__link color: $color-text text-decoration: none
&:hover, &:focus color: $color-primary
&--active color: $color-primary font-weight: $font-weight-bold
Acceptable Nesting .component // Pseudo-elements &::before, &::after content: ''
// States &:hover, &:focus, &:active // State styles
// Modifiers &--variant // Modifier styles
// Media queries +respond-to("md") // Responsive styles
Functions // _functions.sass
// Color functions @function tint($color, $percentage) @return mix(white, $color, $percentage)
@function shade($color, $percentage) @return mix(black, $color, $percentage)
// 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
// Spacing helper @function spacing($multiplier) @return $spacing-unit * $multiplier
// Usage .element background: tint($color-primary, 20%) border-color: shade($color-primary, 10%) font-size: px-to-rem(18) padding: spacing(3)
Placeholders and Extend // Define placeholders %clearfix &::after content: '' display: table clear: both
%list-reset list-style: none margin: 0 padding: 0
%button-reset appearance: none background: none border: none padding: 0 font: inherit cursor: pointer
// Usage .container @extend %clearfix
.nav-list @extend %list-reset
.icon-button @extend %button-reset
Loops and Iteration Generate Utility Classes // Spacing utilities $directions: ("": "", "t": "-top", "r": "-right", "b": "-bottom", "l": "-left")
@each $abbr, $dir in $directions @for $i from 0 through 8 .m#{$abbr}-#{$i} margin#{$dir}: spacing($i) .p#{$abbr}-#{$i} padding#{$dir}: spacing($i)
// Color utilities @each $name, $color in $colors .text-#{$name} color: $color .bg-#{$name} background-color: $color
Grid Generation $grid-columns: 12
@for $i from 1 through $grid-columns .col-#{$i} width: percentage($i / $grid-columns)
// Responsive columns @each $bp, $width in $breakpoints @media (min-width: $width) @for $i from 1 through $grid-columns .col-#{$bp}-#{$i} width: percentage($i / $grid-columns)
Conditionals =theme-button($variant) @if $variant == "primary" background: $color-primary color: white @else if $variant == "secondary" background: transparent color: $color-primary border: 2px solid $color-primary @else if $variant == "danger" background: $color-error color: white @else background: $color-text-muted color: white
.btn-primary +theme-button("primary")
.btn-secondary +theme-button("secondary")
Modern Module System Using @use and @forward // _variables.sass $primary: #3498db
// _mixins.sass @use 'variables' as vars
=themed-element color: vars.$primary
// _index.sass (barrel file) @forward 'variables' @forward 'mixins'
// main.sass @use 'abstracts'
.element +abstracts.themed-element
Performance Tips Keep selector specificity low (prefer single class selectors) Avoid !important except for utility overrides Use @use instead of deprecated @import Limit @extend usage across files Compile without source maps in production Let autoprefixer handle vendor prefixes Code Style Guidelines Use 2 spaces for indentation (critical in Sass) Use single quotes for strings One blank line between rule sets Group related properties together Comment non-obvious code Use meaningful variable names Keep lines under 80 characters when possible Property Order .element // Positioning position: relative top: 0 right: 0 z-index: 10
// Display & Box Model display: flex width: 100% padding: $spacing-md margin: $spacing-sm 0
// Typography font-family: $font-family-base font-size: $font-size-base line-height: $line-height-base color: $color-text
// Visual background: $color-background border: 1px solid $color-border border-radius: $border-radius-md box-shadow: $shadow-sm
// Animation transition: all $transition-base
// Misc cursor: pointer