scss-variable-extractor 1.6.3 → 1.6.5

package/THEME-GUIDE.md

@@ -0,0 +1,289 @@
+# Theme Generation and Global Styles Example
+
+This guide demonstrates the new features for theme generation and global styles preservation.
+
+## 1. Generate Theme Structure
+
+First, generate a complete theme structure for your Angular Material app:
+
+```bash
+# Analyze existing styles and generate themes
+npx scss-extract generate-themes ./src --analyze --output ./src/styles
+```
+
+This creates:
+
+```
+src/styles/
+├── _theme-base.scss          # Shared variables (spacing, typography)
+├── _theme-light.scss         # Light mode colors
+├── _theme-dark.scss          # Dark mode colors
+├── themes.scss               # Material theme loader
+├── _css-variables.scss       # CSS custom properties
+└── _component-theme-mixin.scss  # Theme mixin template
+```
+
+## 2. Modernize Components (Preserve Global Styles)
+
+Next, refactor your components to remove ::ng-deep and !important while preserving the styles globally:
+
+```bash
+# Preview changes
+npx scss-extract modernize ./src --dry-run
+
+# Apply modernization with global preservation
+npx scss-extract modernize ./src --global-styles ./src/styles/global-overrides.scss
+```
+
+**Before (component-a.component.scss):**
+
+```scss
+.container {
+  padding: 16px;
+
+  ::ng-deep .mat-dialog-container {
+    border-radius: 8px !important; // Override Material's default
+  }
+
+  .header {
+    color: #1976d2 !important; // Prevent parent override
+  }
+}
+```
+
+**After modernization:**
+
+**component-a.component.scss:**
+
+```scss
+.container {
+  padding: 16px;
+
+  // ng-deep and !important removed - see global-overrides.scss
+}
+```
+
+**src/styles/global-overrides.scss:**
+
+```scss
+/* Moved from component-a.component.scss - requires !important for specificity */
+.container .mat-dialog-container {
+  border-radius: 8px !important;
+}
+
+/* Moved from component-a.component.scss - requires !important for specificity */
+.container .header {
+  color: #1976d2 !important;
+}
+```
+
+✅ **Benefits:**
+
+- Styles are preserved with proper specificity
+- No parent component overrides
+- Follows Angular Material v15+ best practices
+- Centralized global styles for easier maintenance
+
+## 3. Set Up Theme Switching
+
+Import the generated themes in your `styles.scss`:
+
+```scss
+@use './styles/themes';
+@use './styles/global-overrides';
+```
+
+Add theme toggle to your app component:
+
+**app.component.ts:**
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+  styleUrls: ['./app.component.scss'],
+})
+export class AppComponent {
+  isDarkMode = false;
+
+  constructor() {
+    // Check user preference or localStorage
+    const savedTheme = localStorage.getItem('theme');
+    this.isDarkMode = savedTheme === 'dark';
+  }
+
+  toggleTheme() {
+    this.isDarkMode = !this.isDarkMode;
+    localStorage.setItem('theme', this.isDarkMode ? 'dark' : 'light');
+  }
+}
+```
+
+**app.component.html:**
+
+```html
+<div [class.dark-theme]="isDarkMode">
+  <mat-toolbar color="primary">
+    <span>My App</span>
+    <span class="spacer"></span>
+    <button mat-icon-button (click)="toggleTheme()">
+      <mat-icon>{{ isDarkMode ? 'light_mode' : 'dark_mode' }}</mat-icon>
+    </button>
+  </mat-toolbar>
+
+  <router-outlet></router-outlet>
+</div>
+```
+
+## 4. Use Theme Variables in Components
+
+Instead of hardcoded values, use the generated theme variables:
+
+**Before:**
+
+```scss
+.my-card {
+  padding: 16px;
+  margin: 24px;
+  border-radius: 8px;
+  background: #ffffff;
+  color: rgba(0, 0, 0, 0.87);
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+```
+
+**After:**
+
+```scss
+@use '../../styles/theme-base' as base;
+
+.my-card {
+  padding: base.$spacing-md;
+  margin: base.$spacing-lg;
+  border-radius: base.$border-radius-md;
+  background: var(--surface-color);
+  color: var(--text-primary);
+  box-shadow: base.$shadow-sm;
+}
+```
+
+✅ **Benefits:**
+
+- Automatic dark/light mode switching
+- Consistent spacing and design tokens
+- No hardcoded values
+- Easy theme updates
+
+## 5. Create Component Theme Mixins (Advanced)
+
+For components that need different colors in light/dark themes:
+
+**my-component.theme.scss:**
+
+```scss
+@use '@angular/material' as mat;
+
+@mixin component-theme($theme) {
+  $color-config: mat.get-color-config($theme);
+
+  @if $color-config != null {
+    $primary: map.get($color-config, 'primary');
+    $background: map.get($color-config, 'background');
+
+    .my-special-component {
+      background-color: mat.get-color-from-palette($background, 'card');
+      border-left: 4px solid mat.get-color-from-palette($primary);
+
+      &__header {
+        background-color: mat.get-color-from-palette($primary);
+        color: mat.get-color-from-palette($primary, 'default-contrast');
+      }
+    }
+  }
+}
+```
+
+Then include in `themes.scss`:
+
+```scss
+@use './my-component.theme' as my-component;
+
+// Light theme
+@include my-component.component-theme($light-theme);
+
+// Dark theme
+.dark-theme {
+  @include my-component.component-theme($dark-theme);
+}
+```
+
+## 6. Auto-Format Code
+
+Keep your code consistently formatted:
+
+```bash
+# Format all files
+npm run format
+
+# Check formatting (CI/CD)
+npm run format:check
+```
+
+The formatter runs automatically before releases.
+
+## Complete Workflow Example
+
+```bash
+# 1. Generate theme structure
+npx scss-extract generate-themes ./src --analyze
+
+# 2. Extract hardcoded values to variables
+npx scss-extract refactor ./src --output ./src/styles/_variables.scss
+
+# 3. Modernize components (preserve global styles)
+npx scss-extract modernize ./src --global-styles ./src/styles/global-overrides.scss
+
+# 4. Detect and migrate Bootstrap (if applicable)
+npx scss-extract detect-bootstrap ./src
+npx scss-extract migrate-bootstrap ./src
+
+# 5. Format code
+npm run format
+
+# 6. Run tests and commit
+npm test
+git add .
+git commit -m "feat: Implement theme system and modernize styles"
+```
+
+## Best Practices Summary
+
+✅ **DO:**
+
+- Use theme variables for all colors
+- Use base variables for spacing, typography, shadows
+- Move global styles to dedicated files
+- Use CSS custom properties for runtime theme switching
+- Create component theme mixins for complex theming
+- Format code regularly
+
+❌ **DON'T:**
+
+- Use ::ng-deep (use theme mixins instead)
+- Hardcode colors (use theme variables)
+- Hardcode spacing (use base spacing scale)
+- Use ViewEncapsulation.None unnecessarily
+- Mix !important in component files (move to global)
+
+## Result
+
+🎨 **Professional Theme System:**
+
+- Dark and light modes
+- Consistent design tokens
+- Maintainable global styles
+- No ViewEncapsulation issues
+- Material Design aligned
+- Easy to extend and customize