Theme System Integration for AI Components

How to properly use the theme-system in AI components without conflicts

Theme System Integration for AI Components

🎯 Overview

This document explains how to properly integrate the theme-system with AI components, avoiding mixin conflicts and following SCSS best practices.

❌ The Problem

Initially, we created ai-design-system.scss with its own mixins like button-base and glass-effect, which conflicted with the existing theme-system mixins of the same name.

// ❌ BAD: Creating duplicate mixins causes conflicts
@mixin button-base {
  // ... AI-specific button styles
}

@mixin glass-effect {
  // ... AI-specific glass effect
}

✅ The Solution

1. Use Theme-System Mixins (Namespaced)

Import the theme-system with a namespace and use its mixins directly:

// ✅ CORRECT: Import theme-system with namespace
// Note: SCSS doesn't use TS path aliases, use actual file path
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/index.scss' as theme;
@use '../../styles/ai-design-system.scss' as *;

.my-button {
  // Use theme-system's button-base mixin (no conflict!)
  @include theme.buttons-button-base;
  
  // Add AI-specific overrides
  color: $ai-text-primary;
  border-radius: $ai-border-radius-sm;
}

2. AI Design System Structure

The ai-design-system.scss file now:

Defines only CSS custom properties (design tokens)
Imports theme-system for mixins
Provides AI-specific mixins with unique names (prefixed with ai-)

// libs/libs-ai/gograb-ai/src/lib/styles/ai-design-system.scss

// Import theme-system mixins separately (for proper namespacing)
// Note: SCSS doesn't use TS path aliases, use actual file paths
@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;

// Define CSS custom properties
:root {
  --ai-primary: #8b5cf6;
  --ai-secondary: #6366f1;
  // ... more tokens
}

// SCSS variables (reference CSS properties)
$ai-primary: var(--ai-primary);
$ai-secondary: var(--ai-secondary);

// AI-specific mixins (unique names, no conflicts!)
@mixin ai-glass-effect {
  background: rgba(30, 41, 59, 0.6);
  backdrop-filter: blur(8px);
  border: 1px solid rgba(255, 255, 255, 0.1);
}

@mixin ai-card-base {
  @include ai-glass-effect;
  border-radius: $ai-border-radius-md;
  padding: var(--ai-space-lg);
}

// ❌ DO NOT define button-base here!
// Use theme.buttons-button-base in components instead

3. Component SCSS Structure

Every AI component should follow this pattern:

// component.scss

// 1. Import theme-system (namespaced)
// Note: SCSS doesn't use TS path aliases, use actual file path
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/index.scss' as theme;

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

// 3. Component-specific root class
.my-component {
  // Use CSS custom properties
  padding: var(--ai-space-lg);
  color: $ai-text-primary;
  
  // Nested elements (following SCSS rules)
  &__header {
    background: $ai-surface-1;
    
    &-title {
      font-size: $ai-font-size-2xl;
    }
  }
  
  &__button {
    // Use theme-system mixins
    @include theme.buttons-button-base;
    
    // Add component-specific styling
    background: $ai-primary;
    color: $ai-text-primary;
    
    &:hover {
      background: $ai-secondary;
    }
  }
  
  &__card {
    // Use AI-specific mixins
    @include ai-glass-effect;
    padding: var(--ai-space-xl);
  }
}

📋 Available Theme-System Mixins

Button Mixins (namespace: `theme.buttons-*`)

@include theme.buttons-button-base;       // Base button structure
@include theme.buttons-button-primary;    // Primary button styling
@include theme.buttons-button-secondary;  // Secondary button styling
@include theme.buttons-button-ghost;      // Ghost/transparent buttons

Effect Mixins (namespace: `theme.effects-*`)

@include theme.effects-glass-effect;        // Glass morphism effect
@include theme.effects-glass-effect-dark;   // Dark mode glass effect
@include theme.effects-themed-glass;        // Theme-colored glass effect
@include theme.effects-neumorphism;         // Soft UI neumorphic effects

Utility Mixins (namespace: `theme.utils-*`)

@include theme.utils-flex-center;          // Center content with flexbox
@include theme.utils-absolute-fill;        // Fill parent absolutely
@include theme.utils-truncate;             // Truncate text with ellipsis
@include theme.utils-smooth-transition;    // Consistent transitions
@include theme.utils-glass-effect($bg, $blur, $border); // Parameterized glass

Color Mixins (namespace: `theme.theme-colors-*`)

@include theme.theme-colors-theme-primary;   // Apply primary theme colors
@include theme.theme-colors-theme-secondary; // Apply secondary theme colors
@include theme.theme-colors-theme-card;      // Themed card styling

🎨 AI Design Tokens

Colors

// Status colors
$ai-success: var(--ai-success);   // #22c55e
$ai-warning: var(--ai-warning);   // #f59e0b
$ai-danger: var(--ai-danger);     // #ef4444
$ai-info: var(--ai-info);         // #3b82f6

// Tier-specific colors
$ai-primary: var(--ai-primary);               // #8b5cf6 (Platform)
$ai-cursor-primary: var(--ai-cursor-primary); // #f59e0b (Cursor)
$ai-space-primary: var(--ai-space-primary);   // #ec4899 (Space)

Surfaces

$ai-surface-1: var(--ai-surface-1); // rgba(30, 41, 59, 0.6)
$ai-surface-2: var(--ai-surface-2); // rgba(0, 0, 0, 0.3)
$ai-surface-3: var(--ai-surface-3); // rgba(0, 0, 0, 0.2)

Typography

$ai-text-primary: var(--ai-text-primary);     // 95% white
$ai-text-secondary: var(--ai-text-secondary); // 70% white
$ai-text-tertiary: var(--ai-text-tertiary);   // 50% white

$ai-font-size-sm: var(--ai-font-size-sm);     // 0.75rem
$ai-font-size-md: var(--ai-font-size-md);     // 0.875rem
$ai-font-size-lg: var(--ai-font-size-lg);     // 1rem
$ai-font-size-xl: var(--ai-font-size-xl);     // 1.125rem
$ai-font-size-2xl: var(--ai-font-size-2xl);   // 1.5rem
$ai-font-size-3xl: var(--ai-font-size-3xl);   // 1.75rem

Spacing

$ai-space-xs: var(--ai-space-xs);     // 0.25rem
$ai-space-sm: var(--ai-space-sm);     // 0.5rem
$ai-space-md: var(--ai-space-md);     // 1rem
$ai-space-lg: var(--ai-space-lg);     // 1.5rem
$ai-space-xl: var(--ai-space-xl);     // 2rem
$ai-space-2xl: var(--ai-space-2xl);   // 2.5rem
$ai-space-3xl: var(--ai-space-3xl);   // 3rem

Border Radius

$ai-border-radius-sm: var(--ai-border-radius-sm);  // 6px
$ai-border-radius-md: var(--ai-border-radius-md);  // 12px
$ai-border-radius-lg: var(--ai-border-radius-lg);  // 20px

🚀 Migration Checklist

When creating or updating AI components:

Import @use '@theme-system/theme-styles' as theme; at the top
Import @use '../../styles/ai-design-system.scss' as *; for AI tokens
Use theme.buttons-* for button styling
Use theme.utils-* for utility mixins
Use ai-glass-effect for glass morphism effects
Use AI design tokens ($ai-*) for colors, spacing, typography
Follow component-specific class naming (e.g., .my-component__element)
Nest children inside parents (max 4 levels deep)
Use CSS custom properties (var(--ai-*)) in values

📚 Real-World Examples

Example 1: Button with Theme-System

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

.action-button {
  // Use theme-system button-base
  @include theme.buttons-button-base;
  
  // Add AI-specific styling
  background: linear-gradient(135deg, $ai-primary, $ai-secondary);
  color: $ai-text-primary;
  border-radius: $ai-border-radius-sm;
  padding: var(--ai-space-sm) var(--ai-space-md);
  
  &:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 12px rgba($ai-primary, 0.3);
  }
}

Example 2: Card with Glass Effect

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

.info-card {
  // Use AI glass effect
  @include ai-glass-effect;
  padding: var(--ai-space-xl);
  border-radius: $ai-border-radius-md;
  
  &__header {
    display: flex;
    align-items: center;
    gap: var(--ai-space-md);
    margin-bottom: var(--ai-space-lg);
    
    &-icon {
      font-size: $ai-font-size-2xl;
    }
    
    &-title {
      font-size: $ai-font-size-xl;
      color: $ai-text-primary;
      font-weight: 600;
    }
  }
  
  &__content {
    color: $ai-text-secondary;
    line-height: 1.6;
  }
}

Example 3: Stats Card with Multiple Effects

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

.stat-card {
  @include ai-glass-effect;
  padding: var(--ai-space-xl);
  border-radius: $ai-border-radius-md;
  transition: all var(--ai-transition);
  
  &:hover {
    transform: translateY(-4px);
    box-shadow: 0 8px 24px rgba($ai-primary, 0.2);
  }
  
  &__value {
    font-size: $ai-font-size-3xl;
    font-weight: 700;
    color: $ai-text-primary;
    background: linear-gradient(135deg, $ai-primary, $ai-secondary);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
    background-clip: text;
  }
  
  &__label {
    font-size: $ai-font-size-sm;
    color: $ai-text-tertiary;
    text-transform: uppercase;
    letter-spacing: 0.05em;
  }
  
  &--success &__value {
    background: linear-gradient(135deg, $ai-success, #10b981);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
  }
}

⚠️ Common Mistakes to Avoid

1. Creating Duplicate Mixins

// ❌ BAD: Redefining existing theme-system mixins
@mixin button-base {
  // This conflicts with theme.buttons-button-base!
}

// ✅ GOOD: Use theme-system mixins
@include theme.buttons-button-base;

2. Not Using Namespaces

// ❌ BAD: No namespace, potential conflicts
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/index.scss';

.button {
  @include button-base; // Which button-base?!
}

// ✅ GOOD: Use namespaces
@use 'libs/theme-system/theme-styles/src/lib/styles/mixins/index.scss' as theme;

.button {
  @include theme.buttons-button-base; // Clear!
}

3. Hardcoding Values

// ❌ BAD: Hardcoded values
.card {
  padding: 24px;
  color: rgba(255, 255, 255, 0.7);
  border-radius: 12px;
}

// ✅ GOOD: Use design tokens
.card {
  padding: var(--ai-space-xl);
  color: $ai-text-secondary;
  border-radius: $ai-border-radius-md;
}

4. Generic Class Names

// ❌ BAD: Generic class names (conflicts across components)
.header {
  // ...
}

.content {
  // ...
}

// ✅ GOOD: Component-specific class names
.my-dashboard {
  &__header {
    // ...
  }
  
  &__content {
    // ...
  }
}

🎯 Key Takeaways

Always import theme-system with namespace: @use 'libs/theme-system/theme-styles/src/lib/styles/mixins/index.scss' as theme;
Use theme-system mixins: @include theme.buttons-button-base; not @include button-base;
Use AI design tokens: $ai-primary, $ai-spacing-xl, etc.
Prefix AI-specific mixins: @mixin ai-glass-effect not @mixin glass-effect
Follow SCSS nesting rules: Max 4 levels, children inside parents
Use component-specific class names: .my-component__element not .element
Use CSS custom properties: var(--ai-primary) for runtime theming

📖 Related Documentation

SCSS Rules - Complete SCSS development rules
Theme System Overview - Theme system architecture
AI Design System - AI design tokens

Session: 9
SessionID: 9.1
Status: ✅ Complete

Theme System Integration for AI Components

🎯 Overview

❌ The Problem

✅ The Solution

1. Use Theme-System Mixins (Namespaced)

2. AI Design System Structure

3. Component SCSS Structure

📋 Available Theme-System Mixins

Button Mixins (namespace: theme.buttons-*)

Effect Mixins (namespace: theme.effects-*)

Utility Mixins (namespace: theme.utils-*)

Color Mixins (namespace: theme.theme-colors-*)

🎨 AI Design Tokens

Colors

Surfaces

Typography

Spacing

Border Radius

🚀 Migration Checklist

📚 Real-World Examples

Example 1: Button with Theme-System

Example 2: Card with Glass Effect

Example 3: Stats Card with Multiple Effects

⚠️ Common Mistakes to Avoid

1. Creating Duplicate Mixins

2. Not Using Namespaces

3. Hardcoding Values

4. Generic Class Names

🎯 Key Takeaways

📖 Related Documentation

Button Mixins (namespace: `theme.buttons-*`)

Effect Mixins (namespace: `theme.effects-*`)

Utility Mixins (namespace: `theme.utils-*`)

Color Mixins (namespace: `theme.theme-colors-*`)