@c8y/style 1023.37.0 → 1023.42.1

package/branding-login.less

@@ -1,4 +1,4 @@
-@import 'variables/login-vars.less';
+@import 'variables/_login-vars.less';
 
 // font-faces are declared here so that font-files are not loaded in other brandings
 @import (css) '~@fontsource/public-sans/400.css';

package/helper-scripts/README-variable-imports.md

@@ -0,0 +1,155 @@
+# 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).

package/helper-scripts/README.md

@@ -0,0 +1,104 @@
+# Helper Scripts
+
+Build and maintenance scripts for the @c8y/style package.
+
+## Scripts
+
+### `convert-scss-to-less.sh`
+Semi-automated SCSS to LESS converter with syntax transformation.
+
+**Usage:**
+```bash
+# Convert all modified SCSS files
+./helper-scripts/convert-scss-to-less.sh --all
+
+# Convert specific file (interactive)
+./helper-scripts/convert-scss-to-less.sh styles/path/to/file.scss
+
+# Auto-convert without prompts (used by pre-commit hook)
+./helper-scripts/convert-scss-to-less.sh --yes --all
+
+# Dry run (preview changes only)
+./helper-scripts/convert-scss-to-less.sh --dry-run styles/path/to/file.scss
+```
+
+**Features:**
+- Converts SCSS syntax to LESS (@use → @import, $var → @var, @mixin → .mixin)
+- Transforms mixin parameter separators (commas → semicolons)
+- Converts @extend to :extend() syntax
+- Warns about complex patterns (@if/@else, @content)
+- Respects skip list (`scss-to-less-skip`)
+- Calls specialized converter for stroke icons
+- Verifies compilation after conversion
+
+### `convert-stroke-icons-to-less.js`
+Specialized Node.js converter for stroke icon files.
+
+**Usage:**
+```bash
+node ./helper-scripts/convert-stroke-icons-to-less.js
+```
+
+**Purpose:**
+- Handles complex stroke icon file conversion
+- Called automatically by `convert-scss-to-less.sh` when processing icon files
+
+### `sync-scss-to-less.sh`
+Checks if LESS files are in sync with modified SCSS files.
+
+**Usage:**
+```bash
+./helper-scripts/sync-scss-to-less.sh
+```
+
+**Purpose:**
+- Detects when SCSS files have been modified
+- Warns if corresponding LESS files haven't been updated
+- Suggests conversion commands
+
+### `test-compile.sh`
+Quick compilation test for both LESS and SCSS.
+
+**Usage:**
+```bash
+# Run directly
+./helper-scripts/test-compile.sh
+
+# Or via npm
+npm test
+```
+
+**Checks:**
+- LESS compilation succeeds
+- SCSS compilation succeeds
+- Output file sizes match (within 5%)
+- Displays deprecation warnings
+
+## Configuration Files
+
+### `scss-to-less-skip`
+
+Lists files that should NOT be automatically converted.
+
+Files in this list require manual synchronization due to complex syntax patterns that the converter cannot reliably handle.
+
+See `../markdown-files/MANUAL-SYNC-FILES.md` for details on manually maintained files.
+
+## Git Hook Integration
+
+The `convert-scss-to-less.sh` script is automatically run by the pre-commit hook (`.husky/pre-commit`) when SCSS files are modified on `develop` or `feat/*` branches.
+
+## Directory Structure
+
+```
+packages/style/
+├── helper-scripts/              # All build/maintenance scripts
+│   ├── README.md                # This file
+│   ├── scss-to-less-skip        # Config: files to skip during conversion
+│   ├── convert-scss-to-less.sh  # Main SCSS→LESS converter
+│   ├── convert-stroke-icons-to-less.js  # Specialized icon converter
+│   ├── sync-scss-to-less.sh     # Sync checker
+│   └── test-compile.sh          # Compilation test
+└── markdown-files/              # Documentation
+    └── MANUAL-SYNC-FILES.md     # Manual sync documentation
+```