// Import functions and mixins (in order)
@import "path/to/functions"; // Functions for individual values
@import "path/to/mixins"; // Mixins for complex operations

.my-component {
  // 🎨 Colors - identical API to JS version
  background: color("background.default");
  color: color("text.secondary", 0.8);
  border: 1px solid color("border.default");

  // 📏 Spacing - supports all JS features
  padding: spacing(4); // → "1rem"
  margin: spacing("1/2"); // → "50%"
  gap: spacing("[10vh]"); // → "10vh"

  // ✨ Typography - complete preset application
  @include typography-styles("heading.large");

  // 📱 Responsive design
  @include up("md") {
    padding: spacing(6);
    @include typography-styles("heading.display");
  }

  // 🌓 Other design tokens
  border-radius: radius("md");
  box-shadow: shadow("lg");
  z-index: z-index("modal");
}

// 📱 Responsive typography example
.responsive-heading {
  @include responsive-typography(
    (
      "default": "heading.small",
      "md": "heading.medium",
      "lg": "heading.large",
    )
  );
}

// 🎯 1. Identical API to JavaScript
.component {
  // Same function names, same parameters, same results
  background: color(
    "background.default"
  ); // ✓ Same as JS: color("background.default")
  padding: spacing(4); // ✓ Same as JS: spacing(4)
  box-shadow: shadow("md"); // ✓ Same as JS: shadow("md")
}

// 🔥 2. SCSS-Only Superpowers
.advanced {
  // Multi-property application with mixins
  @include typography-styles(
    "heading.large"
  ); // Applies 5 CSS properties at once

  // Responsive breakpoint mixins
  @include up("md") {
    @include typography-styles("heading.display");
  }

  // Utility mixins for common patterns
  @include text-ellipsis(); // Single-line text truncation
  @include text-ellipsis-multiline(3); // Multi-line text truncation
}

// 🎨 3. Zero Learning Curve
// If you know the JS API, you already know the SCSS API!
.button {
  // JS: { background: color("background.primary", { alpha: 0.9 }) }
  background: color("background.primary", 0.9); // Same result in SCSS

  // JS: { padding: spacingList([2, 4]) }
  padding: spacing-list(2, 4); // Same result in SCSS
}

// 🚀 1. Correct Import Order (Critical!)
@import "path/to/functions"; // Must be first - provides function definitions
@import "path/to/mixins"; // Must be second - uses functions internally

// 🎯 2. Use Functions for Individual Values
.card {
  background: color("background.default");
  padding: spacing(4);
  border-radius: radius("md");
  box-shadow: shadow("sm");
}

// 🔥 3. Use Mixins for Complex Operations
.heading {
  @include typography-styles("heading.large"); // 5 properties applied at once
  @include text-ellipsis(); // Multiple utility properties
}

// 📱 4. Responsive Design Patterns
.component {
  // Base styles with functions
  padding: spacing(4);
  @include typography-styles("body.medium");

  // Responsive with mixins
  @include up("md") {
    padding: spacing(6);
    @include typography-styles("body.large");
  }

  @include up("lg") {
    @include typography-styles("heading.small");
  }
}

// 🎨 5. Advanced Responsive Typography
.hero-title {
  @include responsive-typography(
    (
      "default": "heading.medium",
      // Mobile
      "md": "heading.large",
      // Tablet
      "lg": "heading.display",
      // Desktop
    )
  );
}

// 📦 SCSS Performance Tips
.optimized {
  // ✅ Efficient: Use functions for individual properties
  padding: spacing(4);
  color: color("text.default");

  // ✅ Efficient: Use mixins for multiple properties
  @include typography-styles("body.large");

  // ❌ Avoid: Don't call functions inside loops
  // Use variables instead when possible
  $base-spacing: spacing(4);

  &::before {
    margin: $base-spacing;
  }

  &::after {
    margin: $base-spacing;
  }
}