CSS / SCSS Standards

7.1 Methodology: BEM (Block, Element, Modifier)

All class names must follow the BEM naming convention:

• Block: a standalone entity meaningful on its own (e.g., .header, .user-profile).

• Element: a component part of a block that has no standalone meaning. Separated from the block by double underscore __ (e.g., .header__logo, .user-profile__avatar).

• Modifier: a variant or state of a block or element. Separated by double dash -- (e.g., .header--sticky, .user-profile__avatar--large).

Blocks, elements, and modifiers are all written in kebab-case (lowercase with hyphens).

Examples:

7.2 Selectors and Specificity

• Avoid ID selectors (#my-element) for styling. Use classes only.

• Keep specificity low. Never chain more than two class selectors to avoid !important wars.

• Do not use !important except to override third-party library styles that cannot be influenced otherwise. Each usage must be accompanied by a comment explaining why it is necessary.

• Avoid tag selectors for generic structural styling; confine tag selectors to reset/normalize styles only. Within components, use component-specific classes.

7.3 Variables and Magic Numbers

• No magic numbers or colors: All colors, font stacks, spacing units, breakpoints, and z‑index values must be assigned to SCSS variables in centralized files.

• Variables files:

  • _colors.scss: primary, secondary, status colors.

  • _typography.scss: font families, sizes, weights, line heights.

  • _spacing.scss: consistent padding/margin scale (e.g., 4px, 8px, 16px).

  • _breakpoints.scss: media query breakpoints.

• Z‑index management: Use a _z-index.scss map to define z‑index layers (e.g., dropdown, modal, toast) and avoid manual integer values.

7.4 Nesting

• Maximum nesting depth: 3 levels (including the parent selector). Deep nesting generates overly specific selectors and makes the code harder to override.

• Avoid nesting for the sake of nesting: Write flat selectors where possible. Use the & parent selector for pseudo-classes, pseudo-elements, and BEM modifiers.

  // Good .card { &__title { } &:hover { } &--featured { } } // Bad .card { .body { .text { .icon { } } } }

7.5 Formatting

• Indentation: 2 spaces per indent level.

• Declaration ordering within a rule:

  1. Extends (@extend, @include)

  2. Positioning (position, top, right, bottom, left, z-index)

  3. Display and box model (display, box-sizing, width, height, margin, padding, border)

  4. Typography (font-*, line-height, text-*)

  5. Visual (background, color, box-shadow)

  6. Other

• One selector per line in multi-selector rules.

• Space after colon in declarations, one declaration per line.

• Trailing semicolon required at the end of every declaration.

• No trailing whitespace, end each file with a single newline.

7.6 Responsive Design and Mobile-First

• Mobile-first approach: Write base styles for the smallest screen, then use min-width media queries to scale up.

  .container { display: block; @media (min-width: $breakpoint-md) { display: flex; } }

• Breakpoints: Use only the predefined variables from _breakpoints.scss. Do not write raw pixel values.

• Avoid media queries nested inside individual selectors when a separate file per component/view can hold responsive rules, but it is acceptable to keep them co-located for readability.

7.7 Component Styles (Angular Specific)

• View encapsulation: Use the default ViewEncapsulation.Emulated to isolate styles. If None is required (e.g., styles that need to affect projected content), document the reason.

• Use :host for styling the component root element. Use :host-context for theme-based variations sparingly.

• ::ng-deep is deprecated and must not be used. If you need to pierce encapsulation, consider alternative approaches (e.g., shared global styles, CSS custom properties).

• Global styles (styles.scss) should contain only high-level resets, typography defaults, and utility classes. Do not place component-level overrides here.

7.8 Preprocessors and Mixins

• Use SCSS exclusively (not Sass indent syntax).

• Mixins are encouraged for repetitive patterns (e.g., text truncation, breakpoint media queries, clearfix). Place mixins in a _mixins.scss partial.

• Extend (@extend) with caution: it can create unexpected selector bloat. Prefer mixins for sharing styles.

• Functions are allowed for calculations (e.g., spacing scale, color lightness), but they must be simple and documented.

7.9 Linting and Enforcement

• All stylesheets are checked by stylelint in the CI pipeline, using the team’s shared configuration.

• Rules aligned with this document include:

  • max-nesting-depth: 3

  • declaration-no-important (with a review exception mechanism)

  • number-max-precision: 3

  • selector-max-id: 0

  • Enforced kebab-case for class names, variables, mixins, functions.

  • Enforced alphabetical ordering of properties (optional, but recommended for readability).