Front-End Styling (CSS)

1. Core Principles

• Maintainability over Brevity: Code is read far more often than it is written. Explicit class names and structures are preferred over clever hacks.
• Component-Based: Styles should be scoped to components, avoiding global pollution.
• Mobile-First: Design for the smallest screen first, then use min-width media queries to enhance the layout for larger screens.
• Predictability: A developer should be able to look at a class name and know exactly what it does and where it belongs.

2. Formatting & Syntax

Consistency in formatting makes the codebase easier to scan and debug.

• Indentation: Use 2 spaces (soft tabs).
• Brackets:
  • Opening brace { on the same line as the selector, preceded by one space.
  • Closing brace } on its own line.
• Spacing:
  • Include a space after the colon : in properties.
  • Separate multiple selectors with a newline.
  • Separate rulesets with an empty line.
• Quotes: Use double quotes "" for attribute selectors and content strings.
• Zero Units: Do not use units for zero values (e.g., margin: 0; not margin: 0px;).
• Generic Font Families: The requirement to always include a generic fallback (e.g., sans-serif)

Example

/* ✅ DO */
.card,
.card-alt {
  display: block;
  margin-bottom: 20px;
  padding: 1rem;
  background-color: #ffffff;
}

/* ❌ DON'T */
.card, .card-alt {
    display:block;
    margin-bottom: 20px;
    padding: 1rem;
    background-color: #fff
}

3. Naming Conventions (BEM)

We strictly follow the BEM (Block Element Modifier) methodology to keep specificity low and semantic meaning high.

• Block: The standalone component (e.g., .btn, .modal).
• Element: A child part of the block, denoted by two underscores (e.g., .btn__icon, .modal__header).
• Modifier: A variation, denoted by two hyphens (e.g., .btn--primary, .modal--large).

Specificity Rules

• No IDs: Never use ID selectors (#header) for styling. IDs are reserved for JavaScript hooks and anchor links.
• No Type Selectors: Avoid unqualified type selectors (e.g., div, span, h1) in component styles to prevent style leakage.
• JavaScript Hooks: Do not use BEM classes for JS bindings. Use a dedicated js- prefixed class (e.g., .js-toggle-modal) which should have no styles attached.

4. Pre-processor Specifics (SCSS & LESS)

4.1. Variables

• Naming: Use kebab-case (e.g., $brand-primary, @font-size-base).
• Usage:
  • Define all colors, fonts, z-indexes, and spacing measurements in a centralized variables file.
  • Never use "magic numbers" or hardcoded hex values in component files.

SCSS Example:

// variables.scss
$spacing-md: 16px;
$color-error: #e74c3c;

// component.scss
.alert {
  padding: $spacing-md; // ✅ Good
  color: $color-error;  // ✅ Good
  margin: 15px;         // ❌ Bad (Magic number)
}

4.2 Nesting

• Depth Limit: Do not nest more than 3 levels deep. Deep nesting increases file size and creates specificity wars.
• Usage: Use nesting primarily for BEM element targeting and pseudo-states (:hover, :focus).

The "Inception" Rule:

/* ✅ DO */
.nav {
  &__item {
    color: red;
  }
}

/* ❌ DON'T */
.nav {
  ul {
    li {
      a {
        span { ... } /* Too deep! */
      }
    }
  }
}

4.3. Mixins vs. Extend

• Mixins: Preferred. Use for grouping properties or handling vendor prefixes.
• Extend: Avoid. @extend breaks the source order of CSS and can group selectors unexpectedly, leading to difficult debugging and bloated files.

5. Architecture (The 7-1 Pattern)

Structure your Sass/Less directories into 7 folders and 1 main file.

1. abstracts/: Variables, Mixins, Functions (outputs no CSS).
2. base/: Reset, Typography, global rules.
3. components/: Specific UI widgets (Buttons, Cards, Modals).
4. layout/: Global layout regions (Header, Footer, Grid, Sidebar).
5. pages/: Page-specific styles (keep this minimal).
6. themes/: Distinct themes (e.g., Dark Mode, Admin).
7. vendors/: Third-party CSS (Bootstrap, jQuery UI).
8. main.scss: The entry point that imports all above.

6. Responsive Design & Units

• Layout: Use relative units (%, vw, vh, fr) for containers.
• Typography: Use rem for font-size. This respects the user's browser settings.
• Spacing: Use rem or em for padding/margin to ensure spacing scales with typography.
• Media Queries:
  • Write min-width queries (Mobile First).
  • Nest media queries inside the selector they modify.

.sidebar {
  width: 100%;

  @media (min-width: 768px) {
    width: 250px;
  }
}



Css
.sidebar {
width: 100%;
}
@media (min-width: 768px) {
  .sidebar {
    width: 250px;
  }
}

7. Performance

• Animation: Only animate transform and opacity. Animating properties like width, height, top, or left causes expensive browser reflows.
• Selectors: Avoid the universal selector * inside complex components.
• Imports:
  • CSS: Avoid @import in plain CSS (blocks parallel loading).
  • SCSS/LESS: @import (or @use) is acceptable as it compiles to a single file.

8. Accessibility (A11y)

• Hiding Content: Do not use display: none for content meant for screen readers. Use a .visually-hidden utility class.
• Focus: Never set outline: 0 or outline: none on focusable elements without providing a visible replacement style.
• Contrast: Ensure text color contrast ratios meet WCAG AA standards (4.5:1 for normal text).

Document - CSS