@c8y/style/helper-scripts/README-variable-imports.md

Styles for Cumulocity IoT applications

# Variable Import Optimization for LESS

## Background

LESS and SCSS handle imports differently:

- **SCSS `@use`**: Module system with **local scope** - each file must explicitly import what it needs
- **LESS `@import`**: **Global scope** - variables imported at entry points are available to all subsequent imports

## The Issue

When migrating from LESS to SCSS (and back), we kept variable imports in every component file:

```less
// Every component file had this:
@import "../../../variables/index.less";
```

This was:
- ✅ **Necessary in SCSS** (module system requires explicit imports)
- ❌ **Redundant in LESS** (variables already available from entry points)

## Entry Points Import Variables

All entry points already import variables at the top:

```less
// main.less → branding.less
@import 'variables/index.less';

// login.less → branding-login.less
@import 'variables/_login-vars.less';
```

Since LESS has global scope, **all subsequent imports** automatically have access to these variables.

## Changes Made

### 1. Updated Conversion Script

Modified `convert-scss-to-less.sh` to automatically remove variable imports from converted LESS files:

```bash
# New section 0e - Remove redundant variable imports
content=$(echo "$content" | sed -E '/@import[[:space:]]+.*variables\/index\.less/d')
content=$(echo "$content" | sed -E '/@import[[:space:]]+.*variables\/_login-vars\.less/d')
```

**Why**: Prevents the pre-commit hook from re-adding variable imports every time you commit SCSS changes.

### 2. Created Cleanup Script

Created `remove-redundant-variable-imports.sh` to clean up existing LESS files:

```bash
./helper-scripts/remove-redundant-variable-imports.sh
```

This script:
- Finds all LESS files with variable imports (except entry points)
- Shows a preview of files to be modified
- Asks for confirmation before making changes
- Removes redundant `@import` statements

### 3. Files That SHOULD Keep Variable Imports

Only entry point files should import variables:

- ✅ `branding.less`
- ✅ `branding-login.less`
- ✅ `styles/login-app.less`

All other files (components, mixins, utilities) get variables from the entry point.

## Benefits

1. **Reduced file size**: ~150 files × 1 line = 150 lines removed
2. **Clearer architecture**: Shows that LESS uses global scope
3. **No accidental overrides**: Can't accidentally redefine variables in component files
4. **Faster compilation**: Fewer imports to process
5. **Easier maintenance**: One source of truth for variables

## Migration Path

To remove redundant imports from existing LESS files:

```bash
cd packages/style
./helper-scripts/remove-redundant-variable-imports.sh
npm test  # Verify compilation still works
git diff  # Review changes
git add .
git commit -m "Remove redundant variable imports from LESS files"
```

## Future Commits

The pre-commit hook now automatically:
1. Converts SCSS → LESS when you commit SCSS changes
2. **Removes variable imports** from the LESS output
3. Stages the updated LESS files
4. Verifies both SCSS and LESS compile successfully

You don't need to do anything special - it's all automatic!

## Technical Details

### LESS Import Chain

```
main.less
  → branding.less
    → variables/index.less ✅ (variables defined here)
    → export.less
      → styles/index.less
        → _mixins.less (has access to variables)
        → base/* (has access to variables)
        → components/* (has access to variables)
```

### SCSS Module Chain

```scss
main.scss
  → branding.scss
    → styles/index.scss
      // Each file with @use has local scope:
      → core/buttons/_buttons.scss
        @use "../../../variables/index" as *; ✅ (needed)
```

## Why Not Remove from Mixins?

You might notice files like `_shadows-helper.less` import variables. These imports are technically redundant BUT:

- **All mixins are imported via `_mixins.less`** which is imported AFTER variables in the entry point
- **Variables are already available** when mixins are loaded
- **Could be removed** but kept for documentation/safety in case import order changes

## FAQs

**Q: Won't my LESS files break without variable imports?**
A: No! LESS has global scope. Once variables are imported at the entry point, they're available everywhere.

**Q: What about SCSS files?**
A: SCSS files MUST keep their `@use` statements. The module system requires explicit imports.

**Q: Will the conversion script re-add them?**
A: No! The updated script automatically removes them during conversion.

**Q: What if I use a component file standalone?**
A: Component files should never be compiled standalone - they must go through an entry point (main.less or login.less).

**Q: Does this affect compilation?**
A: No impact! Both SCSS and LESS compile successfully. The output is identical (1.00% difference).