responsive-scale-mixins 1.0.0 → 1.1.1

package/README.md

@@ -2,148 +2,313 @@
 
 A powerful SCSS mixin system for creating perfectly responsive designs that maintain Figma proportions across all screen sizes.
 
+[![npm version](https://badge.fury.io/js/responsive-scale-mixins.svg)](https://badge.fury.io/js/responsive-scale-mixins)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- **Figma Proportions**: Maintains exact proportions from your Figma designs
+- **Automatic Scaling**: No manual breakpoint calculations needed
+- **Tablet Interpolation**: Smart interpolation between mobile and desktop values
+- **CSS Custom Properties**: Uses modern CSS variables for optimal performance
+- **Framework Agnostic**: Works with any CSS framework or vanilla CSS
+- **TypeScript Ready**: Compatible with CSS Modules and CSS-in-JS solutions
+
 ## 🚀 Quick Start
 
+### Installation
+
+#### npm
+
+```bash
+npm install responsive-scale-mixins
+```
+
+#### Yarn
+
+```bash
+yarn add responsive-scale-mixins
+```
+
+#### pnpm
+
+```bash
+pnpm add responsive-scale-mixins
+```
+
+### Framework-Specific Setup
+
+#### Next.js (App Router)
+
 ```scss
-@import "./src/styles/mixins";
+// app/globals.css or app/styles/globals.scss
+@import "~responsive-scale-mixins";
 
-// Basic usage
-.my-element {
-  @include responsive-scale(font-size, 24, 16);
-  @include responsive-scale(padding, 20 40, 10 20);
+:root {
+  // Define CSS variables globally (required)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
 }
+
+// Import in app/layout.tsx: import './globals.css'
 ```
 
-## 📋 Table of Contents
+#### Next.js (Pages Router)
+
+```scss
+// styles/globals.scss
+@import "~responsive-scale-mixins";
+
+:root {
+  // Define CSS variables globally (required)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
+}
 
-- [Setup](#setup)
-- [Basic Usage](#basic-usage)
-- [Advanced Usage](#advanced-usage)
-- [Property Examples](#property-examples)
-- [Percentage Properties](#percentage-properties)
-- [Tips & Best Practices](#tips--best-practices)
+// Import in pages/_app.js: import '../styles/globals.scss'
+```
 
-## 🔧 Setup
+**Next.js Setup:**
 
-### 1. Import the Mixins
+- **App Router**: Put `:root` in `app/globals.css` (imported in `layout.tsx`)
+- **Pages Router**: Put `:root` in `styles/globals.scss` (imported in `pages/_app.js`)
+- The `:root` selector defines global CSS custom properties accessible everywhere
 
-Add this to your SCSS file:
+#### Create React App
 
 ```scss
-@import "../styles/mixins"; // Adjust path as needed
+// src/index.scss or src/styles/main.scss
+@import "~responsive-scale-mixins";
+
+:root {
+  // Define CSS variables globally (required)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
+}
+
+// Import in src/index.js: import './index.scss'
 ```
 
-### 2. CSS Variables (Already configured in `global.scss`)
+**Create React App Setup:**
+
+- Put `:root` in your main SCSS file (e.g., `src/index.scss`)
+- Import the SCSS file in `src/index.js`
+- The `:root` selector makes CSS variables available app-wide
+
+#### Vue.js
+
+```scss
+// src/assets/styles/main.scss
+@import "~responsive-scale-mixins";
 
-The mixin uses these responsive scale factors:
+:root {
+  // Define CSS variables globally (required)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
+}
 
-- `--computed-scale-factor-px` (Desktop: 1913px)
-- `--computed-tablet-scale-factor-px` (Tablet: 768px)
-- `--computed-mobile-scale-factor-px` (Mobile: 390px)
+// Import in src/main.js: import './assets/styles/main.scss'
+```
 
-## 🎯 Basic Usage
+**Vue.js Setup:**
 
-### Same Value for All Screens
+- Put `:root` in your global SCSS file
+- Import in `src/main.js` or use in a global style resource
+- The `:root` selector defines app-wide CSS variables
 
-When you want the same value across desktop, tablet, and mobile:
+#### Angular
 
 ```scss
-// Single parameter - same value for all breakpoints
-.element {
-  @include responsive-scale(border-radius, 10);
-  @include responsive-scale(font-weight, 500);
+// src/styles.scss (global styles)
+@import "~responsive-scale-mixins";
+
+:root {
+  // Define CSS variables globally (required)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
 }
+
+// This file is automatically included by Angular CLI
 ```
 
-**Output:**
+**Angular Setup:**
 
-```css
-.element {
-  border-radius: calc(var(--computed-scale-factor-px) * 10);
-}
+- Put `:root` in `src/styles.scss` (automatically included by Angular CLI)
+- No manual import needed - Angular handles it
+- The `:root` selector defines global CSS variables
+
+#### Vite + Vue/React
 
-@media (min-width: 768px) and (max-width: 991px) {
-  .element {
-    border-radius: calc(var(--computed-tablet-scale-factor-px) * 10);
-  }
+```scss
+// src/styles/main.scss
+@import "responsive-scale-mixins";
+
+:root {
+  // Customize for your design system (optional)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
 }
+```
+
+#### Gatsby
 
-@media (max-width: 767px) {
-  .element {
-    border-radius: calc(var(--computed-mobile-scale-factor-px) * 10);
-  }
+```scss
+// src/styles/global.scss
+@import "~responsive-scale-mixins";
+
+:root {
+  // Customize for your design system (optional)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
 }
 ```
 
-### Different Values for Desktop & Mobile
+#### Nuxt.js
 
-When desktop and mobile need different values:
+```scss
+// assets/styles/main.scss
+@import "~responsive-scale-mixins";
+
+:root {
+  // Customize for your design system (optional)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
+}
+```
+
+#### SvelteKit
 
 ```scss
-// Two parameters - desktop and mobile values
-.element {
-  @include responsive-scale(font-size, 24, 16);
-  @include responsive-scale(height, 60, 40);
+// src/app.scss
+@import "responsive-scale-mixins";
+
+:root {
+  // Customize for your design system (optional)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
 }
 ```
 
-**Output:**
+#### Astro
 
-```css
-.element {
-  font-size: calc(var(--computed-scale-factor-px) * 24);
-  height: calc(var(--computed-scale-factor-px) * 60);
+```scss
+// src/styles/global.scss
+@import "responsive-scale-mixins";
+
+:root {
+  // Customize for your design system (optional)
+  @include responsive-scale-variables(1440px, 768px, 375px);
+  // Or use defaults: @include responsive-scale-variables();
 }
+```
 
-@media (min-width: 768px) and (max-width: 991px) {
-  .element {
-    font-size: calc(
-      var(--computed-tablet-scale-factor-px) *
-        (16 + var(--tablet-proportion-scale-factor) * (24 - 16))
-    );
-    height: calc(
-      var(--computed-tablet-scale-factor-px) *
-        (40 + var(--tablet-proportion-scale-factor) * (60 - 40))
-    );
-  }
+#### CSS Modules
+
+```scss
+// styles.module.scss
+@import "~responsive-scale-mixins";
+
+// Variables must be in global scope
+// In your main CSS file:
+:root {
+  --computed-scale-factor-px: calc(100vw / 1920);
+  --computed-scale-factor-rem: calc(100vw / 1920 / 16);
+  --computed-tablet-scale-factor-px: calc(100vw / 768);
+  --computed-tablet-scale-factor-rem: calc(100vw / 768 / 16);
+  --computed-mobile-scale-factor-px: calc(100vw / 390);
+  --computed-mobile-scale-factor-rem: calc(100vw / 390 / 16);
+  --tablet-proportion-scale-factor: calc((100vw - 390px) / (1920px - 390px));
 }
 
-@media (max-width: 767px) {
-  .element {
-    font-size: calc(var(--computed-mobile-scale-factor-px) * 16);
-    height: calc(var(--computed-mobile-scale-factor-px) * 40);
-  }
+// Then in your module
+.myClass {
+  @include responsive-scale(font-size, 24, 16);
 }
 ```
 
-## ⚡ Advanced Usage
-
-### REM Units
+#### Tailwind CSS Integration
 
 ```scss
-.element {
-  @include responsive-scale(font-size, 2, 1.5, rem);
+// styles/main.scss
+@import "~responsive-scale-mixins";
+
+:root {
+  @include responsive-scale-variables();
+}
+
+// Use alongside Tailwind
+.custom-element {
+  @include responsive-scale(padding, 20 40, 10 20);
+  @apply bg-blue-500 text-white; // Tailwind classes still work
 }
 ```
 
-### Multi-Value Properties
+#### Styled Components
 
 ```scss
-.element {
-  @include responsive-scale(padding, 20 40 20 40, 10 20 10 20);
-  @include responsive-scale(margin, 0 10, 0 5);
+// If using styled-components with SCSS preprocessing
+import styled from 'styled-components';
+import './styles/responsive-mixins.scss'; // Import in your main file
+
+const StyledComponent = styled.div`
+  ${props => props.theme.responsiveScale('font-size', 24, 16)}
+`;
+```
+
+### Basic Usage
+
+```scss
+// In your main SCSS file
+@import "~responsive-scale-mixins";
+
+// Include variables in your root element (required)
+:root {
+  @include responsive-scale-variables();
+}
+
+// Use the mixin anywhere
+.my-element {
+  @include responsive-scale(font-size, 24, 16);
+  @include responsive-scale(padding, 20 40, 10 20);
 }
 ```
 
-## 📏 Property Examples
+## 📖 API Reference
+
+### `responsive-scale-variables($desktop-width, $tablet-width, $mobile-width)`
+
+Defines the CSS custom properties for scaling calculations.
+
+**Parameters:**
+
+- `$desktop-width`: Design width for desktop (default: 1920px)
+- `$tablet-width`: Design width for tablet (default: 768px)
+- `$mobile-width`: Design width for mobile (default: 390px)
+
+### `responsive-scale($property, $desktop-value, $mobile-value, $unit, $is-percentage, $desktop-relative, $mobile-relative, $important)`
+
+The main responsive scaling mixin.
+
+**Parameters:**
+
+- `$property`: CSS property name (e.g., `font-size`, `padding`)
+- `$desktop-value`: Value for desktop screens
+- `$mobile-value`: Value for mobile screens
+- `$unit`: Unit for scaling (`px` or `rem`, default: `px`)
+- `$is-percentage`: Whether the value is a percentage (default: `false`)
+- `$desktop-relative`: Base value for percentage calculations on desktop
+- `$mobile-relative`: Base value for percentage calculations on mobile
+- `$important`: String to append (e.g., `" !important"` for override, default: `null`)
+
+## 🎯 Examples
 
 ### Typography
 
 ```scss
-.text {
-  @include responsive-scale(font-size, 24, 16);
-  @include responsive-scale(line-height, 1.5, 1.4);
-  @include responsive-scale(letter-spacing, -0.5, -0.3);
+.hero-title {
+  @include responsive-scale(font-size, 48, 32);
+  @include responsive-scale(line-height, 1.2, 1.3);
+  @include responsive-scale(letter-spacing, -1, -0.5);
 }
 ```
 
@@ -151,8 +316,8 @@ When desktop and mobile need different values:
 
 ```scss
 .card {
-  @include responsive-scale(padding, 20 30, 15 20);
-  @include responsive-scale(margin, 0 0 20 0, 0 0 15 0);
+  @include responsive-scale(padding, 32 48, 16 24);
+  @include responsive-scale(margin-bottom, 24, 16);
 }
 ```
 
@@ -161,116 +326,135 @@ When desktop and mobile need different values:
 ```scss
 .button {
   @include responsive-scale(width, 200, 150);
-  @include responsive-scale(height, 50, 40);
+  @include responsive-scale(height, 56, 44);
   @include responsive-scale(border-radius, 8, 6);
 }
 ```
 
-### Borders & Shadows
+### Percentage-based Properties
 
 ```scss
-.box {
-  @include responsive-scale(border-width, 2, 1);
-  @include responsive-scale(border-radius, 10, 8);
+.text {
+  // Letter-spacing as 1% of font-size
+  @include responsive-scale(letter-spacing, 1, 1, px, true, 48, 32);
 }
 ```
 
-## 📊 Percentage Properties
-
-For properties that are percentages of other values:
+### Override Specificity
 
 ```scss
-.element {
+.override-bootstrap {
   @include responsive-scale(
-    letter-spacing,
-    -1.5,
-    // Desktop percentage
-    -1.5,
-    // Mobile percentage
-    px,
-    true,
-    // Is percentage-based
+    font-size,
     24,
-    // Desktop base value (font-size)
-    16 // Mobile base value (font-size)
+    16,
+    px,
+    false,
+    null,
+    null,
+    " !important"
+  );
+  @include responsive-scale(
+    padding,
+    16 32,
+    8 16,
+    px,
+    false,
+    null,
+    null,
+    " !important"
   );
 }
 ```
 
-**Output:**
+## 🔧 Configuration
 
-```css
-.element {
-  letter-spacing: calc(-1.5 / 100 * (var(--computed-scale-factor-px) * 24));
-}
+### Custom Design Widths
+
+Easily customize the design widths to match your project's breakpoints:
 
-@media (min-width: 768px) and (max-width: 991px) {
-  .element {
-    letter-spacing: calc(
-      -1.5 / 100 *
-        (
-          var(--computed-tablet-scale-factor-px) *
-            (16 + var(--tablet-proportion-scale-factor) * (24 - 16))
-        )
-    );
-  }
+```scss
+:root {
+  // Custom design widths (desktop, tablet, mobile)
+  @include responsive-scale-variables(1440px, 768px, 375px);
 }
+```
+
+**Default values:**
+
+- Desktop: 1920px
+- Tablet: 768px
+- Mobile: 390px
 
-@media (max-width: 767px) {
-  .element {
-    letter-spacing: calc(
-      -1.5 / 100 * (var(--computed-mobile-scale-factor-px) * 16)
-    );
-  }
+### REM Units
+
+```scss
+.element {
+  @include responsive-scale(font-size, 3, 2, rem); // 3rem / 2rem
 }
 ```
 
-## 💡 Tips & Best Practices
+### Manual CSS Variables (Alternative)
+
+If you prefer manual control, you can set the CSS variables directly:
 
-### ✅ Do's
+```scss
+:root {
+  --computed-scale-factor-px: calc(100vw / 1440); // Your desktop width
+  --computed-scale-factor-rem: calc(100vw / 1440 / 16);
+  --computed-tablet-scale-factor-px: calc(100vw / 768); // Your tablet width
+  --computed-tablet-scale-factor-rem: calc(100vw / 768 / 16);
+  --computed-mobile-scale-factor-px: calc(100vw / 375); // Your mobile width
+  --computed-mobile-scale-factor-rem: calc(100vw / 375 / 16);
+  --tablet-proportion-scale-factor: calc((100vw - 375px) / (1440px - 375px));
+}
+```
 
-- Use consistent units (px for most cases, rem for typography)
-- Test on multiple screen sizes
-- Use the same base values from your Figma design
-- Combine with your existing CSS variables
+## 📱 Breakpoints
 
-### ❌ Don'ts
+- **Desktop**: ≥992px (scales from desktop design width)
+- **Tablet**: 768px - 991px (interpolated values)
+- **Mobile**: ≤767px (scales from mobile design width)
 
-- Don't mix units in the same property
-- Don't use negative values for dimensions
-- Don't forget to import the mixins
+## 🛠 Development
 
-### 🎨 Visual Guide
+### Building
 
+```bash
+npm install
+# No build step required - pure SCSS
 ```
-Desktop (≥992px) → Uses desktop scale factor
-Tablet (768-991px) → Auto-interpolated values
-Mobile (≤767px) → Uses mobile scale factor
+
+### Testing
+
+```bash
+npm test
 ```
 
-### 🔧 Customization
+## 🤝 Contributing
 
-Adjust scale factors in `global.scss`:
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-```scss
---scale-factor: calc(100vw / 1920); // Change desktop width
---mobile-scale-factor: calc(100vw / 375); // Change mobile width
-```
+## 📄 License
 
-## 📚 Complete Example
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-```scss
-@import "../styles/mixins";
+## 🙏 Acknowledgments
 
-.hero-button {
-  @include responsive-scale(font-size, 20, 16);
-  @include responsive-scale(padding, 15 30, 12 24);
-  @include responsive-scale(border-radius, 8, 6);
-  @include responsive-scale(height, 50, 44);
+- Inspired by Figma's responsive design principles
+- Built for modern web development workflows
+- Compatible with CSS Modules, Styled Components, and traditional CSS
 
-  // Percentage-based
-  @include responsive-scale(letter-spacing, -1, -1, px, true, 20, 16);
-}
-```
+## 📞 Support
+
+- 📧 Email: saheedodulaja@gmail.com
+- 🐛 Issues: [GitHub Issues](https://github.com/Sidodus/responsive-scale-mixins/issues)
+- 📖 Docs: [Full Documentation](https://github.com/Sidodus/responsive-scale-mixins#readme)
+
+---
 
-This creates a perfectly responsive button that scales beautifully across all devices! 🎉
+**Made with ❤️ by [Saheed Odulaja](https://github.com/Sidodus)**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "responsive-scale-mixins",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Powerful SCSS mixins for responsive design with Figma proportions. Automatically scales typography, spacing, and dimensions across desktop, tablet, and mobile breakpoints.",
   "main": "index.scss",
   "style": "index.scss",
@@ -38,7 +38,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Sidodus/responsive-scale-mixins.git"
+    "url": "git+https://github.com/Sidodus/responsive-scale-mixins.git"
   },
   "bugs": {
     "url": "https://github.com/Sidodus/responsive-scale-mixins.git/issues"

package/scss/_mixins.scss

@@ -1,12 +1,12 @@
 /* // ✅ Figma Proportions: Maintains the same proportions as the Figma design.
 
-// // Here’s a SCSS mixin that dynamically calculates font-size, line-height, padding, margins, and other scalable properties across desktop, tablet, and mobile screens.
+// // Here's a SCSS mixin that dynamically calculates font-size, line-height, padding, margins, and other scalable properties across desktop, tablet, and mobile screens.
 // ✅ Consistent Scaling: No need to manually adjust for medium screens.
 // ✅ Reusable: Works for font-size, line-height, margins, paddings, etc.
 // ✅ Automatic Scaling: Dynamically scales values based on the screen size.
 
 // 📌 How to Use It
-// Import the mixins in your SCSS file: @import "../styles/mixins";
+// Import the mixins in your SCSS file: @import "~responsive-scale-mixins/scss/mixins";
 // .title {
 //   @include responsive-scale(font-size, 40, 24);
 //   @include responsive-scale(padding, 20 73, 8 16); // Multi-value
@@ -16,10 +16,11 @@
 //   @include responsive-scale(letter-spacing, -1.5, -1.5, px, true, 40, 24);
 // }
 
-// Parameters: property, desktop-value, mobile-value, unit (default px), is-percentage (default false), desktop-relative, mobile-relative
+// Parameters: property, desktop-value, mobile-value, unit (default px), is-percentage (default false), desktop-relative, mobile-relative, important (default null)
 // Pass values as numbers (e.g., 20 for 20px, 20 73 for 20px 73px).
 // Tablet values are automatically interpolated using the tablet-proportion-scale-factor.
 // For percentage-based values, provide the percentage for desktop and mobile, and the base values (e.g., font-size for letter-spacing).
+// Pass " !important" as the important parameter to append !important to the generated CSS rules.
 // Media queries: Desktop (default), Tablet (768-991px), Mobile (≤767px). */
 
 @function scaled-value($val, $scale-var, $unit: px) {
@@ -33,7 +34,8 @@
   $unit: px,
   $is-percentage: false,
   $desktop-relative: null,
-  $mobile-relative: null
+  $mobile-relative: null,
+  $important: null
 ) {
   $scale-factor: if(
     $unit == px,
@@ -44,9 +46,10 @@
   // If it's a percentage-based value (like letter-spacing), scale it based on the relative property
   @if $is-percentage == true {
     @if $desktop-relative != null {
-      #{$property}: calc(
+      $calc-value: calc(
         #{$desktop-value} / 100 * (var(#{$scale-factor}) * #{$desktop-relative})
       );
+      #{$property}: #{$calc-value}#{$important};
     }
 
     @media screen and (min-width: 768px) and (max-width: 991px) {
@@ -56,7 +59,7 @@
         unquote("--computed-tablet-scale-factor-rem")
       );
       @if $desktop-relative != null and $mobile-relative != null {
-        #{$property}: calc(
+        $calc-value: calc(
           #{$mobile-value} /
             100 *
             (
@@ -68,6 +71,7 @@
                 )
             )
         );
+        #{$property}: #{$calc-value}#{$important};
       }
     }
 
@@ -78,11 +82,12 @@
         unquote("--computed-mobile-scale-factor-rem")
       );
       @if $mobile-relative != null {
-        #{$property}: calc(
+        $calc-value: calc(
           #{$mobile-value} /
             100 *
             (var(#{$mobile-scale-factor}) * #{$mobile-relative})
         );
+        #{$property}: #{$calc-value}#{$important};
       }
     }
   } @else {
@@ -95,9 +100,10 @@
           scaled-value($val, $scale-factor, $unit)
         );
       }
-      #{$property}: $desktop-scaled;
+      #{$property}: #{$desktop-scaled}#{$important};
     } @else {
-      #{$property}: scaled-value($desktop-value, $scale-factor, $unit);
+      $scaled-value: scaled-value($desktop-value, $scale-factor, $unit);
+      #{$property}: #{$scaled-value}#{$important};
     }
 
     @media screen and (min-width: 768px) and (max-width: 991px) {
@@ -123,9 +129,9 @@
             )
           );
         }
-        #{$property}: $tablet-scaled;
+        #{$property}: #{$tablet-scaled}#{$important};
       } @else {
-        #{$property}: calc(
+        $calc-value: calc(
           var(#{$tablet-scale-factor}) *
             (
               #{$mobile-value} +
@@ -133,6 +139,7 @@
                 (#{$desktop-value} - #{$mobile-value})
             )
         );
+        #{$property}: #{$calc-value}#{$important};
       }
     }
 
@@ -150,9 +157,10 @@
             scaled-value($val, $mobile-scale-factor, $unit)
           );
         }
-        #{$property}: $mobile-scaled;
+        #{$property}: #{$mobile-scaled}#{$important};
       } @else {
-        #{$property}: scaled-value($mobile-value, $mobile-scale-factor, $unit);
+        $scaled-value: scaled-value($mobile-value, $mobile-scale-factor, $unit);
+        #{$property}: #{$scaled-value}#{$important};
       }
     }
   }