Correct SCSS Import Pattern for Theme-System

The proper way to import and use theme-system mixins in SCSS

Correct SCSS Import Pattern for Theme-System

🎯 The Problem

SCSS modules with nested namespaces cannot be accessed through a single parent namespace.

❌ What Doesn't Work:

// This doesn't work!
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/index.scss' as theme;

.my-button {
  @include theme.buttons-button-base; // ❌ ERROR: Undefined mixin
}

Why? The index.scss file has:

@use './ux-buttons.scss' as buttons;

So buttons is a namespace within the index. When you import the index as theme, you can't access nested namespaces like theme.buttons.button-base in SCSS.

✅ The Solution: Import Each Mixin File Separately

// ✅ CORRECT: Import each mixin file with its own namespace
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/ux-buttons.scss' as buttons;
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/ux-effects.scss' as effects;
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/utils.scss' as utils;

// Import AI design tokens
@use '../../styles/ai-design-system.scss' as *;

// Now use the mixins with their proper namespaces
.my-button {
  @include buttons.button-base; // ✅ Works!
  @include utils.smooth-transition; // ✅ Works!
}

.my-card {
  @include ai-glass-effect; // ✅ AI-specific mixin
}

📋 Standard Import Template

For All AI Components:

// ========================================
// THEME-SYSTEM MIXINS (Import separately)
// ========================================
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/ux-buttons.scss' as buttons;
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/ux-effects.scss' as effects;
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/utils.scss' as utils;

// ========================================
// AI DESIGN TOKENS
// ========================================
@use '../../styles/ai-design-system.scss' as *;

// ========================================
// COMPONENT STYLES
// ========================================
.my-ai-component {
  // Use theme-system mixins
  &__button {
    @include buttons.button-base;
    color: $ai-text-primary;
  }
  
  // Use AI-specific mixins
  &__card {
    @include ai-glass-effect;
    padding: var(--ai-space-lg);
  }
  
  // Use utility mixins
  &__content {
    @include utils.flex-center;
  }
}

🔧 Available Mixin Namespaces

Namespace	File	Available Mixins
`buttons`	`ux-buttons.scss`	`button-base`, `button-primary`, `button-secondary`, `button-ghost`
`effects`	`ux-effects.scss`	`glass-effect`, `glass-effect-dark`, `neumorphism`, `morphing-background`
`utils`	`utils.scss`	`flex-center`, `absolute-fill`, `truncate`, `smooth-transition`, `glass-effect`

💡 Usage Examples

Button Styling:

@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/ux-buttons.scss' as buttons;
@use '../../styles/ai-design-system.scss' as *;

.action-button {
  @include buttons.button-base;
  background: $ai-primary;
  color: $ai-text-primary;
  padding: var(--ai-space-sm) var(--ai-space-md);
  
  &:hover {
    background: $ai-secondary;
  }
}

Card with Effects:

@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/utils.scss' as utils;
@use '../../styles/ai-design-system.scss' as *;

.info-card {
  @include ai-glass-effect;
  padding: var(--ai-space-xl);
  border-radius: $ai-border-radius-md;
  
  &__header {
    @include utils.flex-center;
    gap: var(--ai-space-md);
  }
}

Complex Component:

@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/ux-buttons.scss' as buttons;
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/utils.scss' as utils;
@use '../../styles/ai-design-system.scss' as *;

.dashboard-card {
  @include ai-glass-effect;
  padding: var(--ai-space-xl);
  
  &__header {
    @include utils.flex-center;
    justify-content: space-between;
  }
  
  &__action-btn {
    @include buttons.button-base;
    @include utils.smooth-transition;
    background: $ai-primary;
  }
}

⚠️ Common Mistakes

1. Trying to Use Index Import

// ❌ WRONG
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/index.scss' as theme;
@include theme.buttons-button-base; // Undefined mixin!

2. Using TypeScript Path Aliases

// ❌ WRONG (TS aliases don't work in SCSS)
@use '@theme-system/theme-styles' as theme;

3. Not Importing What You Need

// ❌ WRONG (buttons namespace not imported)
@include buttons.button-base; // Undefined!

✅ Correct Pattern Checklist

Import each mixin file separately
Use actual file paths (not TS aliases)
Use proper namespaces (buttons, effects, utils)
Import AI design system for tokens
Use AI-specific mixins for AI components

🎯 Key Rules

Always import mixin files separately - Don't use index.scss
Use actual file paths - SCSS doesn't support TS path aliases
Use proper namespaces - buttons.button-base not theme.buttons-button-base
Import only what you need - Don't import all mixins if you only use buttons
Use AI mixins for AI styling - ai-glass-effect not glass-effect

Session: 9
SessionID: 9.1
Status: ✅ Complete
Build Status: ✅ All Errors Fixed