# **Front-End Styling (CSS)**

| Field   | Value              |
| ------- | ------------------ |
| Version | 1.0.0              |
| Author  | Rakesh Lokhande    |
| Target  | All Frontend Teams |
| Scope   | CSS, SCSS, LESS    |

### **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](https://docs.google.com/document/d/1CU_KDWtQcGuYa6LDK_kU0E_EjqR0AlTed7-1o-iiT3s/edit?usp=sharing)