eva-css-fluid 2.0.0 → 2.0.6

package/README.md

@@ -64,6 +64,38 @@ yarn add eva-css-fluid
 
 **Migrating from another framework?** See the [Migration Guide](./MIGRATION.md) for detailed instructions.
 
+## 🚦 Which Configuration Method Should I Use?
+
+EVA CSS can be configured in two ways. **Choose based on your project needs:**
+
+### For Quick Start / Learning
+👉 **Use SCSS Variables** - Everything in one file, works immediately
+
+### For Production Projects
+Choose based on your needs:
+
+| You want... | Use... |
+|-------------|--------|
+| Simplicity, no build scripts | **SCSS Variables** (`@use ... with ()`) |
+| Centralized config, multiple SCSS files | **JSON Config** (requires custom build script) |
+| Watch mode without complexity | **SCSS Variables** |
+| Config validation, better DX | **JSON Config** (requires custom build script) |
+
+💡 **You can start with SCSS variables and migrate to JSON later - the generated CSS is identical!**
+
+### Option Comparison
+
+| Feature | SCSS Variables | JSON Config |
+|---------|----------------|-------------|
+| **Setup complexity** | ⭐ Simple | ⭐⭐⭐ Requires script |
+| **Works with `npx sass`** | ✅ Yes, immediately | ⚠️ No, needs custom script |
+| **Config location** | Inside SCSS file | Separate `eva.config.cjs` |
+| **Multiple SCSS files** | ⚠️ Config duplicated | ✅ Shared config |
+| **Validation** | ❌ No | ✅ `npx eva-css validate` |
+| **Generated CSS** | ✅ Identical output | ✅ Identical output |
+
+**See detailed workflows below** for implementation examples.
+
 ## 🚀 Quick Start
 
 ### New Project (Recommended)
@@ -120,9 +152,39 @@ npx sass --load-path=node_modules styles/main.scss:styles/main.css
 
 ### Using SCSS with Custom Configuration
 
-**This is the main feature of EVA CSS!** You can configure EVA CSS in two ways:
+**This is the main feature of EVA CSS!** Extract sizes from your design and configure EVA to generate only what you need.
+
+#### Option 1: SCSS Variables (Recommended for Beginners)
+
+**Direct configuration in your SCSS file** - Works immediately with `npx sass`:
+
+```scss
+// Example: Sizes extracted from Figma design
+@use 'eva-css-fluid' with (
+  $sizes: 4, 8, 16, 32, 64, 128,        // 👈 Change these to YOUR design sizes!
+  $font-sizes: 14, 16, 20, 24, 32,      // 👈 Change these to YOUR font sizes!
+  $build-class: true,
+  $px-rem-suffix: false
+);
+```
 
-#### Option 1: JSON Configuration (Recommended)
+**Compile immediately:**
+
+```bash
+npx sass --load-path=node_modules styles/main.scss:styles/main.css
+```
+
+✅ **Advantages:**
+- Works immediately with standard Sass compilation
+- No additional build scripts needed
+- Perfect for watch mode: `npx sass --watch ...`
+- Great for learning and simple projects
+
+⚠️ **Note:** If you import EVA in multiple SCSS files, you'll need to duplicate the configuration.
+
+#### Option 2: JSON Configuration (Advanced - Requires Build Script)
+
+**Centralized configuration file** - Better for complex projects with multiple SCSS files:
 
 Create `eva.config.cjs` in your project root:
 
@@ -136,42 +198,72 @@ module.exports = {
 };
 ```
 
-Or add to your `package.json`:
-
-```json
-{
-  "eva": {
-    "sizes": [4, 8, 16, 32, 64, 128],
-    "fontSizes": [14, 16, 20, 24, 32],
-    "buildClass": true
-  }
-}
-```
-
-Then simply import EVA CSS:
+Then in your SCSS:
 
 ```scss
 @use 'eva-css-fluid';
 ```
 
-And build with the integrated script:
+⚠️ **IMPORTANT:** JSON configuration requires a **custom build script** to work. SCSS cannot execute JavaScript directly.
 
+**You have two choices:**
+
+**A) Use the EVA package's build script** (for building EVA itself):
 ```bash
+# This is only for building the EVA CSS package itself, NOT for your project
+cd node_modules/eva-css-fluid
 npm run build
-# Configuration is automatically loaded from eva.config.cjs or package.json
 ```
 
-#### Option 2: SCSS Variables
+**B) Create your own build script** (recommended for user projects):
 
-```scss
-// Example: Sizes extracted from Figma design
-@use 'eva-css-fluid' with (
-  $sizes: 4, 8, 16, 32, 64, 128,        // 👈 Change these to YOUR design sizes!
-  $font-sizes: 14, 16, 20, 24, 32,      // 👈 Change these to YOUR font sizes!
-  $build-class: true,
-  $px-rem-suffix: false
-);
-```
+1. Copy the build script template:
+   ```bash
+   # Create scripts directory if needed
+   mkdir -p scripts
+
+   # Copy the ready-to-use script from the monorepo examples
+   cp node_modules/eva-css-fluid/../../examples/user-scripts/build-with-config.js scripts/build-eva.js
+
+   # Or download directly from GitHub
+   curl -o scripts/build-eva.js https://raw.githubusercontent.com/nkdeus/eva-framework/main/examples/user-scripts/build-with-config.js
+   ```
+
+2. Add npm script to your `package.json`:
+   ```json
+   {
+     "scripts": {
+       "build:css": "node scripts/build-eva.js styles/main.scss dist/main.css",
+       "watch:css": "nodemon --watch eva.config.cjs --watch styles/ --exec 'npm run build:css'"
+     }
+   }
+   ```
+
+3. Build your CSS:
+   ```bash
+   npm run build:css
+   ```
+
+**What the script does:**
+- Reads your `eva.config.cjs` configuration
+- Converts JSON config → SCSS variables
+- Compiles SCSS with the injected config
+- Handles HEX → OKLCH color conversion automatically
+
+📚 **See [examples/user-scripts/README.md](../../examples/user-scripts/README.md) for detailed documentation**
+
+✅ **Advantages:**
+- Single config file shared across multiple SCSS files
+- Config validation with `npx eva-css validate`
+- Cleaner SCSS files
+- Better for large projects
+
+⚠️ **Disadvantages:**
+- Requires custom build script setup
+- More complex workflow
+- Not compatible with standard `npx sass` command
+
+💡 **New to EVA CSS?** Start with **Option 1 (SCSS Variables)** and migrate to JSON config later if needed!
 
 **Real example from a Figma project:**
 
@@ -189,6 +281,60 @@ npm run build
 // var(--4), var(--8), var(--16), var(--32), var(--64), var(--120), var(--141)
 ```
 
+## ❓ FAQ - Configuration
+
+### Q: Why doesn't `@use 'eva-css-fluid'` automatically load `eva.config.cjs`?
+
+**A:** SCSS cannot execute JavaScript during compilation. The `eva.config.cjs` file must be read **before** SCSS compilation and transformed into SCSS variables.
+
+**Solutions:**
+- **Simple:** Use `@use ... with ()` directly in your SCSS (no script needed)
+- **Advanced:** Create a build script that reads the config and injects it into SCSS (see Option 2 above)
+
+### Q: What's the difference between "JSON config" and "SCSS variables"?
+
+**A:** The generated CSS is **100% identical**. It's only a matter of workflow organization:
+
+| Method | Configuration Location | Compilation Command |
+|--------|----------------------|---------------------|
+| SCSS Variables | Inside SCSS file with `@use ... with ()` | `npx sass styles.scss` |
+| JSON Config | Separate `eva.config.cjs` file | Custom script required |
+
+**Choose based on your workflow:**
+- **Simple projects:** SCSS variables (quick and easy)
+- **Complex projects with multiple SCSS files:** JSON config (shared configuration)
+
+### Q: Can I use the `scripts/build-with-config.cjs` from the eva-css package?
+
+**A:** That script is designed to **build EVA CSS itself** (the framework), not your project.
+
+For your project, you need to:
+1. Create your own build script (see template in `examples/user-scripts/`)
+2. Or use SCSS variables with `@use ... with ()` instead
+
+### Q: Which option should I use for my project?
+
+**A:** Follow this decision tree:
+
+```
+Do you have multiple SCSS files that need the same EVA config?
+├─ NO  → Use SCSS Variables (simpler)
+└─ YES → Do you want config validation and centralized settings?
+    ├─ YES → Use JSON Config (requires build script setup)
+    └─ NO  → Use SCSS Variables (simpler, just duplicate config)
+```
+
+### Q: Can I migrate from SCSS variables to JSON config later?
+
+**A:** Yes! Since both methods generate identical CSS, you can switch at any time:
+
+1. Create `eva.config.cjs` with your settings
+2. Set up a build script (see examples/)
+3. Update your SCSS from `@use ... with ()` to `@use 'eva-css-fluid'`
+4. Update your build command
+
+No CSS changes needed!
+
 ## 🎨 Configuration Options
 
 ### JSON Configuration (eva.config.cjs or package.json)
@@ -246,6 +392,30 @@ module.exports = {
 };
 ```
 
+**Real-world example** (Tailwind colors to EVA theme):
+
+```javascript
+// Extract colors from your design system
+module.exports = {
+  theme: {
+    name: 'myproject',
+    colors: {
+      brand: '#3b82f6',    // Tailwind blue-500
+      accent: '#22c55e',   // Tailwind green-500
+      extra: '#a855f7'     // Tailwind purple-500
+    },
+    lightMode: { lightness: 98, darkness: 10 },
+    darkMode: { lightness: 8, darkness: 95 },
+    autoSwitch: true  // Auto dark mode with prefers-color-scheme
+  }
+};
+```
+
+**These HEX colors are automatically converted to:**
+- `#3b82f6` → `oklch(57.4% 0.213 263.8)` (perceptually uniform blue)
+- `#22c55e` → `oklch(72.6% 0.200 147.6)` (perceptually uniform green)
+- `#a855f7` → `oklch(60.8% 0.248 302.7)` (perceptually uniform purple)
+
 **Available colors:** `brand`, `accent`, `extra`, `dark`, `light`
 
 **Color formats:**
@@ -481,6 +651,251 @@ var(--brand-b_)  // More brighter
 }
 ```
 
+## ❗ Troubleshooting
+
+### Common Issues and Solutions
+
+#### "The target selector was not found" with @extend
+
+**Error:**
+```
+Error: The target selector was not found.
+Use "@extend .w-64 !optional" to avoid this error.
+```
+
+**Cause:** You're using `@use` instead of `@forward` when trying to extend EVA classes.
+
+**Solution:** Use `@forward` to expose EVA classes in your module:
+
+```scss
+// ❌ Wrong - @use doesn't expose classes for @extend
+@use 'eva-css-fluid';
+
+.my-class {
+  @extend .w-64;  // Error!
+}
+
+// ✅ Correct - @forward exposes classes
+@forward 'eva-css-fluid';
+
+.my-class {
+  @extend .w-64;  // Works!
+}
+```
+
+#### Theme colors not appearing in compiled CSS
+
+**Problem:** You defined colors in `eva.config.cjs` but they don't show up in the output CSS.
+
+**Solutions:**
+
+1. **Using JSON config?** Make sure you're using the build script:
+   ```bash
+   # Won't work - SCSS can't read .cjs files
+   npx sass styles/main.scss dist/main.css
+
+   # Use this instead
+   node scripts/build-eva.js styles/main.scss dist/main.css
+   ```
+
+2. **Import colors module** if using SCSS variables:
+   ```scss
+   @use 'eva-css-fluid/src/colors' with (
+     $theme-name: 'myapp',
+     $theme-colors: (
+       brand: (lightness: 62.8, chroma: 0.258, hue: 29.23),
+       // ... more colors
+     )
+   );
+   ```
+
+3. **Apply theme class in HTML:**
+   ```html
+   <!-- Without this class, theme colors won't be active -->
+   <body class="current-theme theme-myapp">
+     <h1 class="_c-brand">Now this works!</h1>
+   </body>
+   ```
+
+#### HEX colors not converting to OKLCH
+
+**Problem:** You put HEX colors in `eva.config.cjs` but get an error or they don't work.
+
+**Cause:** The build script needs `eva-colors` to convert HEX → OKLCH automatically.
+
+**Solution:**
+
+1. Install `eva-colors` as a dependency:
+   ```bash
+   npm install eva-colors
+   ```
+
+2. Or convert colors manually:
+   ```bash
+   npx eva-color convert "#ff5733"
+   # Output: oklch(62.8% 0.258 29.23)
+   ```
+
+3. Then use OKLCH format in config:
+   ```javascript
+   // eva.config.cjs
+   module.exports = {
+     theme: {
+       colors: {
+         brand: { lightness: 62.8, chroma: 0.258, hue: 29.23 }
+       }
+     }
+   };
+   ```
+
+#### Configuration not loading / "Invalid configuration" error
+
+**Problem:** Your `eva.config.cjs` isn't being read or validation fails.
+
+**Checklist:**
+
+1. **File location:** Must be in project root (same level as `package.json`)
+2. **File name:** Must be exactly `eva.config.cjs` or `eva.config.js`
+3. **Syntax:** Must use `module.exports`, not ESM `export`
+4. **Validate config:**
+   ```bash
+   npx eva-css validate
+   ```
+
+**Common mistakes:**
+
+```javascript
+// ❌ Wrong - ESM syntax
+export default {
+  sizes: [16, 24]
+};
+
+// ✅ Correct - CommonJS
+module.exports = {
+  sizes: [16, 24]
+};
+```
+
+#### Dark mode toggle not working
+
+**Problem:** Clicking toggle button doesn't switch themes.
+
+**Required setup:**
+
+1. **HTML structure:**
+   ```html
+   <body class="current-theme theme-myapp">
+     <!-- Both classes required ^^ -->
+     <button onclick="document.body.classList.toggle('toggle-theme')">
+       Toggle Dark Mode
+     </button>
+   </body>
+   ```
+
+2. **Theme configuration:**
+   ```javascript
+   // eva.config.cjs
+   module.exports = {
+     theme: {
+       name: 'myapp',  // Must match class: .theme-myapp
+       lightMode: { lightness: 96.4, darkness: 6.4 },
+       darkMode: { lightness: 5, darkness: 95 },
+       autoSwitch: false  // Set true for auto prefers-color-scheme
+     }
+   };
+   ```
+
+3. **Toggle class:** The `.toggle-theme` class triggers dark mode when present.
+
+#### CSS file size is huge (100KB+)
+
+**Problem:** Generated CSS file is very large.
+
+**Solutions:**
+
+1. **Enable custom class mode** to generate only needed classes:
+   ```scss
+   @use 'eva-css-fluid' with (
+     $sizes: (16, 24, 32, 64),
+     $custom-class: true,
+     $class-config: (
+       w: (64,),      // Only .w-64
+       p: (16, 24),   // Only .p-16 and .p-24
+       fs: (16, 24)   // Only .fs-16 and .fs-24
+     )
+   );
+   ```
+   **Result:** Reduces output by ~85%
+
+2. **Use CSS purging** to remove unused classes:
+   ```bash
+   npm install --save-dev eva-css-purge
+   npx eva-purge --css dist/eva.css --content "src/**/*.html"
+   ```
+   **Result:** Typically 60-90% size reduction
+
+3. **Use variables mode** instead of utility classes:
+   ```scss
+   @use 'eva-css-fluid' with (
+     $build-class: false  // No utility classes, only variables
+   );
+   ```
+   **Result:** Much smaller CSS (only variables, no classes)
+
+#### Sass compilation error: "Cannot find module"
+
+**Error:**
+```
+Error: Can't find stylesheet to import.
+  ╷
+1 │ @use 'eva-css-fluid';
+  │ ^^^^^^^^^^^^^^^^^^^^^
+```
+
+**Solutions:**
+
+1. **Add load-path** if using older Sass:
+   ```bash
+   npx sass --load-path=node_modules styles/main.scss dist/main.css
+   ```
+
+2. **Check package is installed:**
+   ```bash
+   npm ls eva-css-fluid
+   # Should show: eva-css-fluid@x.x.x
+   ```
+
+3. **Try explicit path:**
+   ```scss
+   @use '../node_modules/eva-css-fluid/src';
+   ```
+
+#### Watch mode not detecting config changes
+
+**Problem:** Changing `eva.config.cjs` doesn't trigger rebuild.
+
+**Solution:** Use `nodemon` to watch config file:
+
+```json
+{
+  "scripts": {
+    "watch:css": "nodemon --watch eva.config.cjs --watch styles/ --exec 'node scripts/build-eva.js styles/main.scss dist/main.css'"
+  }
+}
+```
+
+Install nodemon:
+```bash
+npm install --save-dev nodemon
+```
+
+#### Need help?
+
+- 📖 [Full Documentation](https://eva-css.xyz/)
+- 💬 [GitHub Issues](https://github.com/nkdeus/eva/issues)
+- 📦 [NPM Package](https://www.npmjs.com/package/eva-css-fluid)
+- 🎯 [Working Examples](../../examples/)
+
 ## 📚 Documentation
 
 - [Full Documentation](https://eva-css.xyz/)

package/cli.cjs

@@ -2,10 +2,11 @@
 
 /**
  * EVA CSS CLI
- * Commands for configuration validation and management
+ * Commands for configuration validation and project setup
  */
 
 const { validateConfigCommand, generateScssCommand } = require('./src/config-loader.cjs');
+const { initCommand, setupCommand } = require('./src/cli-commands.cjs');
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -18,21 +19,36 @@ Usage:
   eva-css <command> [options]
 
 Commands:
+  init           Initialize EVA CSS in existing project (creates eva.config.cjs)
+  setup          Complete project setup with workflow choice (SCSS vs JSON)
   validate       Validate eva.config.js or package.json configuration
   generate       Generate SCSS variables from config file
   help           Show this help message
 
 Examples:
-  eva-css validate
-  eva-css generate src/_config-generated.scss
+  eva-css init              # Initialize eva.config.cjs interactively
+  eva-css setup             # Complete setup with file generation
+  eva-css validate          # Validate configuration
+  eva-css generate output.scss
 
-Configuration:
-  Create eva.config.js in your project root or add "eva" key to package.json
-  See: https://eva-css.xyz/configuration
+Getting Started:
+  For new projects:         eva-css setup
+  For existing projects:    eva-css init
+
+Documentation:
+  https://github.com/nkdeus/eva/blob/main/packages/eva-css/README.md
 `);
 }
 
 switch (command) {
+  case 'init':
+    initCommand();
+    break;
+
+  case 'setup':
+    setupCommand();
+    break;
+
   case 'validate':
     validateConfigCommand();
     break;

package/package.json

@@ -1,87 +1,87 @@
 {
-  "name": "eva-css-fluid",
-  "version": "2.0.0",
-  "description": "Fluid design framework with OKLCH colors - Transform static designs into responsive fluid systems",
-  "type": "module",
-  "main": "src/index.scss",
-  "sass": "src/index.scss",
-  "style": "dist/eva.css",
-  "bin": {
-    "eva-css": "./cli.cjs"
-  },
-  "exports": {
-    ".": {
-      "sass": "./index.scss",
-      "style": "./dist/eva.css",
-      "default": "./dist/eva.css"
-    },
-    "./src": {
-      "sass": "./src/index.scss",
-      "default": "./src/index.scss"
-    },
-    "./variables": {
-      "sass": "./src/variables.scss",
-      "default": "./src/variables.scss"
-    },
-    "./core": {
-      "sass": "./src/core.scss",
-      "default": "./src/core.scss"
-    },
-    "./colors": {
-      "sass": "./src/colors-only.scss",
-      "default": "./src/colors-only.scss"
-    },
-    "./src/*": "./src/*.scss",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "src/",
-    "dist/",
-    "index.scss",
-    "cli.cjs",
-    "scripts/",
-    "eva.config.template.js",
-    "README.md",
-    "MIGRATION.md"
-  ],
-  "keywords": [
-    "css",
-    "scss",
-    "sass",
-    "framework",
-    "fluid-design",
-    "oklch",
-    "utility-css",
-    "design-system",
-    "responsive",
-    "eva"
-  ],
-  "scripts": {
-    "build": "node scripts/build-with-config.cjs",
-    "build:min": "node scripts/build-with-config.cjs --min",
-    "build:purge": "node scripts/build-with-config.cjs --purge",
-    "build:sass": "sass src/index.scss dist/eva.css --style=expanded",
-    "build:sass:min": "sass src/index.scss dist/eva.min.css --style=compressed",
-    "watch": "sass --watch src/index.scss dist/eva.css",
-    "dev": "npm run watch",
-    "validate:config": "node cli.cjs validate",
-    "generate:config": "node cli.cjs generate"
-  },
-  "dependencies": {
-    "eva-colors": "^2.0.0"
-  },
-  "devDependencies": {
-    "sass": "^1.94.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/nkdeus/eva.git",
-    "directory": "packages/eva-css"
-  },
-  "author": {
-    "name": "Michaël Tati",
-    "url": "https://ulysse-2029.com/"
-  },
-  "homepage": "https://eva-css.xyz/",
-  "license": "MIT"
+    "name":  "eva-css-fluid",
+    "version":  "2.0.6",
+    "description":  "Fluid design framework with OKLCH colors - Transform static designs into responsive fluid systems",
+    "type":  "module",
+    "main":  "src/index.scss",
+    "sass":  "src/index.scss",
+    "style":  "dist/eva.css",
+    "bin":  {
+                "eva-css":  "./cli.cjs"
+            },
+    "exports":  {
+                    ".":  {
+                              "sass":  "./index.scss",
+                              "style":  "./dist/eva.css",
+                              "default":  "./dist/eva.css"
+                          },
+                    "./src":  {
+                                  "sass":  "./src/index.scss",
+                                  "default":  "./src/index.scss"
+                              },
+                    "./variables":  {
+                                        "sass":  "./src/variables.scss",
+                                        "default":  "./src/variables.scss"
+                                    },
+                    "./core":  {
+                                   "sass":  "./src/core.scss",
+                                   "default":  "./src/core.scss"
+                               },
+                    "./colors":  {
+                                     "sass":  "./src/colors-only.scss",
+                                     "default":  "./src/colors-only.scss"
+                                 },
+                    "./src/*":  "./src/*.scss",
+                    "./package.json":  "./package.json"
+                },
+    "files":  [
+                  "src/",
+                  "dist/",
+                  "index.scss",
+                  "cli.cjs",
+                  "scripts/",
+                  "eva.config.template.js",
+                  "README.md",
+                  "MIGRATION.md"
+              ],
+    "keywords":  [
+                     "css",
+                     "scss",
+                     "sass",
+                     "framework",
+                     "fluid-design",
+                     "oklch",
+                     "utility-css",
+                     "design-system",
+                     "responsive",
+                     "eva"
+                 ],
+    "scripts":  {
+                    "build":  "node scripts/build-with-config.cjs",
+                    "build:min":  "node scripts/build-with-config.cjs --min",
+                    "build:purge":  "node scripts/build-with-config.cjs --purge",
+                    "build:sass":  "sass src/index.scss dist/eva.css --style=expanded",
+                    "build:sass:min":  "sass src/index.scss dist/eva.min.css --style=compressed",
+                    "watch":  "sass --watch src/index.scss dist/eva.css",
+                    "dev":  "npm run watch",
+                    "validate:config":  "node cli.cjs validate",
+                    "generate:config":  "node cli.cjs generate"
+                },
+    "dependencies":  {
+                         "eva-colors":  "^2.0.6"
+                     },
+    "devDependencies":  {
+                            "sass":  "^1.94.1"
+                        },
+    "repository":  {
+                       "type":  "git",
+                       "url":  "https://github.com/nkdeus/eva.git",
+                       "directory":  "packages/eva-css"
+                   },
+    "author":  {
+                   "name":  "Michaël Tati",
+                   "url":  "https://ulysse-2029.com/"
+               },
+    "homepage":  "https://eva-css.xyz/",
+    "license":  "MIT"
 }

package/src/cli-commands.cjs

@@ -0,0 +1,539 @@
+/**
+ * EVA CSS CLI Interactive Commands
+ *
+ * Commands: init, setup
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// CLI colors
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m'
+};
+
+function log(msg) {
+  console.log(msg);
+}
+
+function success(msg) {
+  log(`${colors.green}✅${colors.reset} ${msg}`);
+}
+
+function info(msg) {
+  log(`${colors.blue}ℹ${colors.reset}  ${msg}`);
+}
+
+function error(msg) {
+  log(`${colors.red}❌${colors.reset} ${msg}`);
+}
+
+function title(msg) {
+  log(`\n${colors.bright}${colors.cyan}${msg}${colors.reset}\n`);
+}
+
+// Readline interface for prompts
+function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise(resolve => {
+    rl.question(`${colors.cyan}?${colors.reset} ${question} `, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function select(question, options) {
+  log(`${colors.cyan}?${colors.reset} ${question}`);
+  options.forEach((opt, i) => {
+    const description = opt.description ? ` ${colors.dim}- ${opt.description}${colors.reset}` : '';
+    log(`  ${colors.dim}${i + 1}.${colors.reset} ${opt.label}${description}`);
+  });
+
+  const answer = await prompt(`  Select (1-${options.length}):`);
+  const index = parseInt(answer) - 1;
+
+  if (index >= 0 && index < options.length) {
+    return options[index].value;
+  }
+
+  error('Invalid selection, using default');
+  return options[0].value;
+}
+
+async function confirm(question, defaultValue = true) {
+  const defaultText = defaultValue ? 'Y/n' : 'y/N';
+  const answer = await prompt(`${question} (${defaultText})`);
+
+  if (!answer) return defaultValue;
+  return answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes';
+}
+
+/**
+ * Generate eva.config.cjs template
+ */
+function generateEvaConfig(options) {
+  const { sizes, fontSizes, buildClass, debug, workflow } = options;
+
+  return `/**
+ * EVA CSS Configuration
+ *
+ * This configuration file defines your design tokens.
+ * Customize sizes, font sizes, and build options.
+ *
+ * Documentation: https://github.com/nkdeus/eva/blob/main/packages/eva-css/docs/JSON-CONFIG.md
+ */
+
+module.exports = {
+  // Design sizes - extracted from your design system
+  // These become CSS variables: var(--4), var(--8), var(--16), etc.
+  sizes: [${sizes.join(', ')}],
+
+  // Font sizes for typography
+  // These become CSS variables: var(--14), var(--16), var(--20), etc.
+  fontSizes: [${fontSizes.join(', ')}],
+
+  // Generate utility classes (.w-64, .p-16, .fs-24, etc.)
+  buildClass: ${buildClass},
+
+  // Show configuration during build (useful for debugging)
+  debug: ${debug},
+
+  // Theme configuration
+  theme: {
+    name: 'eva',
+    colors: {
+      // Using EVA default colors
+      // You can customize: brand, accent, extra
+    },
+
+    lightMode: {
+      lightness: 96.4,  // Light background
+      darkness: 6.4     // Dark text
+    },
+
+    darkMode: {
+      lightness: 5,     // Dark background
+      darkness: 95      // Light text
+    },
+
+    // Auto-switch based on system preference
+    autoSwitch: false
+  }${workflow === 'json' ? `,
+
+  // Optional: CSS purging for production
+  // Uncomment to reduce file size by 60-90%
+  /*
+  purge: {
+    enabled: true,
+    content: ['*.html', 'src/**/*.{js,jsx,tsx,vue}'],
+    css: 'dist/main.css',
+    output: 'dist/main-purged.css',
+    safelist: ['theme-', 'current-', 'toggle-']
+  }
+  */` : ''}
+};
+`;
+}
+
+/**
+ * Generate build script for JSON config workflow
+ */
+function generateBuildScript() {
+  return `#!/usr/bin/env node
+/**
+ * EVA CSS Build Script
+ *
+ * This script loads eva.config.cjs and injects it into SCSS compilation.
+ *
+ * USAGE:
+ *   node scripts/build.js <input.scss> <output.css>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Load EVA configuration from eva.config.cjs
+ */
+function loadConfig() {
+  const configPath = path.join(process.cwd(), 'eva.config.cjs');
+
+  if (!fs.existsSync(configPath)) {
+    console.log('⚠️  No eva.config.cjs found');
+    return null;
+  }
+
+  delete require.cache[require.resolve(configPath)];
+  return require(configPath);
+}
+
+/**
+ * Convert configuration to SCSS variables
+ */
+function generateScssWithParams(config) {
+  const params = [];
+
+  if (config.sizes) {
+    params.push(\`$sizes: (\${config.sizes.join(', ')})\`);
+  }
+
+  if (config.fontSizes) {
+    params.push(\`$font-sizes: (\${config.fontSizes.join(', ')})\`);
+  }
+
+  if (typeof config.buildClass === 'boolean') {
+    params.push(\`$build-class: \${config.buildClass}\`);
+  }
+
+  if (typeof config.debug === 'boolean') {
+    params.push(\`$debug: \${config.debug}\`);
+  }
+
+  return params.join(',\\n  ');
+}
+
+/**
+ * Build CSS from SCSS with configuration injection
+ */
+function buildCss(inputScss, outputCss, config) {
+  if (!fs.existsSync(inputScss)) {
+    console.error(\`❌ Input file not found: \${inputScss}\`);
+    process.exit(1);
+  }
+
+  const outputDir = path.dirname(outputCss);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  const inputDir = path.dirname(inputScss);
+  const inputBase = path.basename(inputScss, '.scss');
+  const tempPath = path.join(inputDir, \`.\${inputBase}-temp.scss\`);
+
+  try {
+    const content = fs.readFileSync(inputScss, 'utf8');
+    let output = content;
+
+    if (config) {
+      const params = generateScssWithParams(config);
+
+      if (params) {
+        output = content.replace(
+          /@use\\s+['"]eva-css\\/index['"];?/g,
+          \`@use 'eva-css/index' with (\\n  \${params}\\n);\`
+        );
+
+        console.log('✅ Config injected into SCSS');
+      }
+    }
+
+    fs.writeFileSync(tempPath, output);
+
+    console.log('🔨 Compiling SCSS...');
+    execSync(
+      \`npx sass --load-path=node_modules \${tempPath}:\${outputCss}\`,
+      { stdio: 'inherit' }
+    );
+
+    if (fs.existsSync(outputCss)) {
+      const stats = fs.statSync(outputCss);
+      const sizeKB = (stats.size / 1024).toFixed(2);
+      console.log(\`✅ CSS compiled: \${outputCss} (\${sizeKB} KB)\`);
+    }
+  } catch (error) {
+    console.error('❌ Build failed:', error.message);
+    process.exit(1);
+  } finally {
+    if (fs.existsSync(tempPath)) {
+      fs.unlinkSync(tempPath);
+    }
+  }
+}
+
+/**
+ * Main execution
+ */
+function main() {
+  const [,, input, output] = process.argv;
+
+  if (!input || !output) {
+    console.log('Usage: node scripts/build.js <input.scss> <output.css>');
+    process.exit(1);
+  }
+
+  console.log('🚀 EVA CSS Build\\n');
+  console.log(\`📥 Input:  \${input}\`);
+  console.log(\`📤 Output: \${output}\\n\`);
+
+  const config = loadConfig();
+  buildCss(input, output, config);
+
+  console.log('\\n✨ Build complete!\\n');
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { loadConfig, generateScssWithParams, buildCss };
+`;
+}
+
+/**
+ * eva-css init command
+ * Initialize EVA CSS in existing project
+ */
+async function initCommand() {
+  try {
+    title('🎨 EVA CSS Initialization');
+
+    // Check if eva.config.cjs already exists
+    const configPath = path.join(process.cwd(), 'eva.config.cjs');
+    if (fs.existsSync(configPath)) {
+      error('eva.config.cjs already exists!');
+      const overwrite = await confirm('Overwrite?', false);
+      if (!overwrite) {
+        log('\nAborted.');
+        process.exit(0);
+      }
+    }
+
+    // Get configuration from user
+    log('');
+    info('Configure your design system:\n');
+
+    const sizesInput = await prompt('Design sizes (comma-separated) [4, 8, 16, 32, 64, 128]:');
+    const sizes = sizesInput ? sizesInput.split(',').map(s => parseInt(s.trim())) : [4, 8, 16, 32, 64, 128];
+
+    const fontSizesInput = await prompt('Font sizes (comma-separated) [14, 16, 20, 24, 32, 48]:');
+    const fontSizes = fontSizesInput ? fontSizesInput.split(',').map(s => parseInt(s.trim())) : [14, 16, 20, 24, 32, 48];
+
+    const buildClass = await confirm('Generate utility classes?', true);
+    const debug = await confirm('Enable debug mode?', false);
+
+    // Generate config file
+    const configContent = generateEvaConfig({
+      sizes,
+      fontSizes,
+      buildClass,
+      debug,
+      workflow: 'json'
+    });
+
+    fs.writeFileSync(configPath, configContent);
+    success('Created eva.config.cjs');
+
+    // Success message
+    title('✅ EVA CSS Initialized!');
+
+    log(`${colors.bright}Next steps:${colors.reset}\n`);
+    log(`  ${colors.dim}1.${colors.reset} Run ${colors.cyan}npx eva-css validate${colors.reset} to verify configuration`);
+    log(`  ${colors.dim}2.${colors.reset} Import EVA CSS in your SCSS: ${colors.dim}@use 'eva-css/index';${colors.reset}`);
+    log(`  ${colors.dim}3.${colors.reset} Use ${colors.cyan}eva-css setup${colors.reset} for full project setup with build scripts\n`);
+
+    log(`${colors.dim}Documentation: https://github.com/nkdeus/eva/blob/main/packages/eva-css/README.md${colors.reset}\n`);
+
+  } catch (err) {
+    error(`Failed to initialize: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * eva-css setup command
+ * Complete project setup with workflow choice
+ */
+async function setupCommand() {
+  try {
+    title('🚀 EVA CSS Project Setup');
+
+    // Choose workflow
+    log('');
+    const workflow = await select('Choose your workflow:', [
+      {
+        label: 'SCSS Variables',
+        value: 'scss',
+        description: 'Simple, works with npx sass directly'
+      },
+      {
+        label: 'JSON Config',
+        value: 'json',
+        description: 'Centralized config, requires build script'
+      }
+    ]);
+
+    log('');
+    info('Configure your design system:\n');
+
+    const sizesInput = await prompt('Design sizes (comma-separated) [4, 8, 16, 32, 64, 128]:');
+    const sizes = sizesInput ? sizesInput.split(',').map(s => parseInt(s.trim())) : [4, 8, 16, 32, 64, 128];
+
+    const fontSizesInput = await prompt('Font sizes (comma-separated) [14, 16, 20, 24, 32, 48]:');
+    const fontSizes = fontSizesInput ? fontSizesInput.split(',').map(s => parseInt(s.trim())) : [14, 16, 20, 24, 32, 48];
+
+    const buildClass = await confirm('Generate utility classes?', true);
+    const debug = await confirm('Enable debug mode?', false);
+
+    log('\n📁 Setting up project files...\n');
+
+    // Create directories
+    if (!fs.existsSync('styles')) {
+      fs.mkdirSync('styles', { recursive: true });
+      success('Created styles/');
+    }
+
+    if (!fs.existsSync('dist')) {
+      fs.mkdirSync('dist', { recursive: true });
+      success('Created dist/');
+    }
+
+    if (workflow === 'json') {
+      // JSON Config workflow
+
+      // 1. Create eva.config.cjs
+      const configContent = generateEvaConfig({ sizes, fontSizes, buildClass, debug, workflow });
+      fs.writeFileSync('eva.config.cjs', configContent);
+      success('Created eva.config.cjs');
+
+      // 2. Create build script
+      if (!fs.existsSync('scripts')) {
+        fs.mkdirSync('scripts', { recursive: true });
+      }
+      fs.writeFileSync('scripts/build.js', generateBuildScript());
+      success('Created scripts/build.js');
+
+      // 3. Create clean SCSS (no config inline)
+      const scssContent = `// EVA CSS
+// Configuration is loaded from eva.config.cjs
+
+@use 'eva-css/index';
+
+// Your custom styles here
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  transition: background 0.3s, color 0.3s;
+}
+`;
+      fs.writeFileSync('styles/main.scss', scssContent);
+      success('Created styles/main.scss');
+
+      // 4. Update or create package.json scripts
+      const packageJsonPath = 'package.json';
+      let packageJson = {};
+
+      if (fs.existsSync(packageJsonPath)) {
+        packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      } else {
+        packageJson = {
+          name: path.basename(process.cwd()),
+          version: '1.0.0',
+          private: true
+        };
+      }
+
+      packageJson.scripts = packageJson.scripts || {};
+      packageJson.scripts.build = 'node scripts/build.js styles/main.scss dist/main.css';
+      packageJson.scripts.watch = 'nodemon --watch styles --watch eva.config.cjs --ext scss,cjs --exec "npm run build"';
+      packageJson.scripts.validate = 'eva-css validate';
+
+      fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+      success('Updated package.json scripts');
+
+      // Success message
+      title('✅ JSON Config Workflow Setup Complete!');
+
+      log(`${colors.bright}Next steps:${colors.reset}\n`);
+      log(`  ${colors.dim}1.${colors.reset} Install dependencies: ${colors.cyan}npm install --save-dev sass nodemon${colors.reset}`);
+      log(`  ${colors.dim}2.${colors.reset} Validate config: ${colors.cyan}npm run validate${colors.reset}`);
+      log(`  ${colors.dim}3.${colors.reset} Build CSS: ${colors.cyan}npm run build${colors.reset}`);
+      log(`  ${colors.dim}4.${colors.reset} Watch mode: ${colors.cyan}npm run watch${colors.reset}\n`);
+
+    } else {
+      // SCSS Variables workflow
+
+      // Create SCSS with inline config
+      const scssContent = `// EVA CSS - SCSS Variables Configuration
+
+@use 'eva-css/index' with (
+  // Design sizes from your design system
+  $sizes: (${sizes.join(', ')}),
+
+  // Font sizes for typography
+  $font-sizes: (${fontSizes.join(', ')}),
+
+  // Generate utility classes
+  $build-class: ${buildClass},
+
+  // Show debug info during build
+  $debug: ${debug}
+);
+
+// Your custom styles here
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  transition: background 0.3s, color 0.3s;
+}
+`;
+      fs.writeFileSync('styles/main.scss', scssContent);
+      success('Created styles/main.scss');
+
+      // Update or create package.json scripts
+      const packageJsonPath = 'package.json';
+      let packageJson = {};
+
+      if (fs.existsSync(packageJsonPath)) {
+        packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      } else {
+        packageJson = {
+          name: path.basename(process.cwd()),
+          version: '1.0.0',
+          private: true
+        };
+      }
+
+      packageJson.scripts = packageJson.scripts || {};
+      packageJson.scripts.build = 'sass --load-path=node_modules styles/main.scss:dist/main.css';
+      packageJson.scripts.watch = 'sass --watch --load-path=node_modules styles/main.scss:dist/main.css';
+
+      fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+      success('Updated package.json scripts');
+
+      // Success message
+      title('✅ SCSS Variables Workflow Setup Complete!');
+
+      log(`${colors.bright}Next steps:${colors.reset}\n`);
+      log(`  ${colors.dim}1.${colors.reset} Install Sass: ${colors.cyan}npm install --save-dev sass${colors.reset}`);
+      log(`  ${colors.dim}2.${colors.reset} Build CSS: ${colors.cyan}npm run build${colors.reset}`);
+      log(`  ${colors.dim}3.${colors.reset} Watch mode: ${colors.cyan}npm run watch${colors.reset}\n`);
+    }
+
+    log(`${colors.dim}Documentation: https://github.com/nkdeus/eva/blob/main/packages/eva-css/README.md${colors.reset}\n`);
+
+  } catch (err) {
+    error(`Setup failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  initCommand,
+  setupCommand
+};