eva-css-fluid 1.0.4 → 2.0.0

package/MIGRATION.md

@@ -0,0 +1,337 @@
+# EVA CSS Migration Guide
+
+This guide helps you migrate from your internal framework to EVA CSS.
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Configuration Changes](#configuration-changes)
+- [Common Gotchas](#common-gotchas)
+- [Breaking Changes](#breaking-changes)
+- [Migration Examples](#migration-examples)
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install eva-css-fluid
+```
+
+### Basic Setup
+
+Replace your old framework import with EVA CSS:
+
+```scss
+// Before (internal framework)
+@import 'internal-framework/styles';
+
+// After (EVA CSS)
+@use 'eva-css-fluid/src' as *;
+```
+
+### With Custom Configuration
+
+```scss
+@use 'eva-css-fluid/src' as * with (
+  $sizes: (4, 8, 12, 16, 24, 32, 48, 64, 96, 128),
+  $font-sizes: (12, 14, 16, 18, 20, 24, 32, 48)
+);
+```
+
+## Configuration Changes
+
+### Required Base Size
+
+**Important**: EVA CSS requires size `16` to be present in your `$sizes` configuration.
+
+```scss
+// ❌ Will throw error
+@use 'eva-css-fluid/src' as * with (
+  $sizes: (8, 24, 32, 64)
+);
+
+// ✅ Correct
+@use 'eva-css-fluid/src' as * with (
+  $sizes: (8, 16, 24, 32, 64)
+);
+```
+
+**Why?** Size 16 (1rem) is used as the base unit for fluid calculations.
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `$sizes` | `4, 8, 12, 16, 24, 32, 48, 64, 96, 128` | Available size values (16 required) |
+| `$font-sizes` | `12, 14, 16, 18, 20, 24, 32, 48` | Font size values |
+| `$build-class` | `true` | Generate utility classes |
+| `$px-rem-suffix` | `false` | Add px/rem debug values |
+| `$name-by-size` | `true` | Use size values in names |
+| `$custom-class` | `false` | Enable selective class generation |
+| `$class-config` | `()` | Configure which classes to generate |
+
+## Common Gotchas
+
+### 1. Import Syntax Change
+
+EVA CSS uses modern Sass `@use` instead of `@import`:
+
+```scss
+// ❌ Old syntax (deprecated)
+@import 'eva-css-fluid/src';
+
+// ✅ New syntax
+@use 'eva-css-fluid/src' as *;
+```
+
+### 2. Custom Class Mode
+
+When using `$custom-class: true`, you **must** provide `$class-config`:
+
+```scss
+// ❌ Will throw error
+@use 'eva-css-fluid/src' as * with (
+  $custom-class: true
+);
+
+// ✅ Correct
+@use 'eva-css-fluid/src' as * with (
+  $custom-class: true,
+  $class-config: (
+    w: (50, 100),
+    px: (24,),     // Note: trailing comma for single-item lists
+    g: (24, 50)
+  )
+);
+```
+
+### 3. Property Names in class-config
+
+Only use valid property keys from the framework:
+
+```scss
+// ❌ Invalid property
+$class-config: (
+  width: (50, 100)  // Use 'w' not 'width'
+);
+
+// ✅ Correct
+$class-config: (
+  w: (50, 100)
+);
+```
+
+**Available properties**: `w`, `mw`, `h`, `p`, `px`, `pr`, `py`, `br`, `mb`, `mr`, `ml`, `mt`, `pt`, `pb`, `g`, `gap`
+
+### 4. Sizes Must Exist in $sizes
+
+All sizes referenced in `$class-config` must exist in your `$sizes` list:
+
+```scss
+// ❌ Will throw error (999 not in $sizes)
+@use 'eva-css-fluid/src' as * with (
+  $sizes: (16, 24, 50, 100),
+  $custom-class: true,
+  $class-config: (
+    w: (50, 999)
+  )
+);
+
+// ✅ Correct
+@use 'eva-css-fluid/src' as * with (
+  $sizes: (16, 24, 50, 100),
+  $custom-class: true,
+  $class-config: (
+    w: (50, 100)
+  )
+);
+```
+
+## Breaking Changes
+
+### Version 1.1.0
+
+#### Added
+
+- **`$class-config` parameter**: New configuration option for custom class mode
+- **Configuration validation**: Helpful error messages for invalid configurations
+- **Required base size**: Size 16 is now required in `$sizes`
+
+#### Changed
+
+- `$custom-class` now requires `$class-config` to be set (if enabled)
+- Empty `$sizes` or `$font-sizes` lists now throw errors
+
+#### Migration Steps
+
+1. Ensure size `16` is in your `$sizes` configuration
+2. If using `$custom-class: true`, add `$class-config` parameter
+3. Test compilation to catch any validation errors
+
+## Migration Examples
+
+### Example 1: From Internal Framework
+
+```scss
+// Before
+@import 'internal-framework';
+
+$spacing: 8px, 16px, 24px, 32px;
+$colors: (
+  primary: #3498db,
+  secondary: #2ecc71
+);
+
+// After
+@use 'eva-css-fluid/src' as * with (
+  $sizes: (8, 16, 24, 32)
+);
+
+// Colors are built-in with OKLCH system
+// Use: var(--brand), var(--accent), etc.
+```
+
+### Example 2: Production Build with Custom Classes
+
+**Scenario**: You want to generate only specific classes to reduce CSS size.
+
+```scss
+// Before (generated all classes)
+@use 'eva-css-fluid/src' as *;
+
+// After (optimized)
+@use 'eva-css-fluid/src' as * with (
+  $sizes: (16, 24, 50, 100),
+  $custom-class: true,
+  $class-config: (
+    w: (50, 100),      // Only width-50 and width-100
+    h: (50, 100),      // Only height-50 and height-100
+    px: (24,),         // Only padding-x-24
+    py: (24,),         // Only padding-y-24
+    g: (24, 50),       // Only gap-24 and gap-50
+    br: (16,)          // Only border-radius-16
+  )
+);
+```
+
+**Result**: Significantly smaller CSS output, perfect for production.
+
+### Example 3: Development Mode
+
+**Scenario**: You're in development and want CSS variables only (no classes).
+
+```scss
+@use 'eva-css-fluid/src' as * with (
+  $build-class: false,    // Don't generate utility classes
+  $px-rem-suffix: true    // Add debug values
+);
+```
+
+Then use in your CSS:
+
+```scss
+.my-component {
+  width: var(--64);
+  padding: var(--16);
+  border-radius: var(--8);
+
+  // Debug values available:
+  // var(--64-px)  → pixel value
+  // var(--64-rem) → rem value
+}
+```
+
+### Example 4: Gradual Migration
+
+**Scenario**: You want to migrate gradually, keeping both frameworks.
+
+```scss
+// Load EVA CSS with custom namespace
+@use 'eva-css-fluid/src' as eva with (
+  $sizes: (16, 24, 32, 48, 64)
+);
+
+// Keep your old framework temporarily
+@import 'old-framework';
+
+// Now you can use both:
+.new-component {
+  padding: var(--eva-16);
+}
+
+.old-component {
+  padding: $old-spacing-md;
+}
+```
+
+## Troubleshooting
+
+### Error: "Size 16 is required as a base size"
+
+**Solution**: Add `16` to your `$sizes` list:
+
+```scss
+@use 'eva-css-fluid/src' as * with (
+  $sizes: (4, 8, 16, 24, 32, 48, 64)  // Add 16 here
+);
+```
+
+### Error: "Unknown property 'xyz' in $class-config"
+
+**Solution**: Use valid property abbreviations. Check the list of available properties in [Common Gotchas](#3-property-names-in-class-config).
+
+### Error: "When $custom-class is true, $class-config must be a map"
+
+**Solution**: Provide a valid `$class-config` map:
+
+```scss
+@use 'eva-css-fluid/src' as * with (
+  $custom-class: true,
+  $class-config: (
+    w: (50, 100),
+    px: (24,)
+  )
+);
+```
+
+### Compilation is Slow
+
+**Solutions**:
+
+1. Use `$custom-class: true` to reduce generated classes
+2. Use `$build-class: false` if you only need CSS variables
+3. Disable `$px-rem-suffix` in production
+
+### CSS Output is Too Large
+
+**Solutions**:
+
+1. Enable custom class mode:
+   ```scss
+   @use 'eva-css-fluid/src' as * with (
+     $custom-class: true,
+     $class-config: (
+       // Only include what you need
+     )
+   );
+   ```
+
+2. Use the `eva-purge` package to remove unused classes:
+   ```bash
+   npm install @eva-css/eva-purge
+   eva-purge input.css output.css --html "**/*.html"
+   ```
+
+## Getting Help
+
+- **Documentation**: [eva-css.xyz](https://eva-css.xyz)
+- **GitHub Issues**: [github.com/nkdeus/eva/issues](https://github.com/nkdeus/eva/issues)
+- **Examples**: See `demo/` folder in the repository
+
+## Next Steps
+
+1. ✅ Complete the migration
+2. 📚 Read the [full documentation](./README.md)
+3. 🎨 Explore the [OKLCH color system](./README.md#-oklch-color-system)
+4. ⚡ Optimize your build with [custom classes](./README.md#custom-class-mode-custom-class-true)

package/README.md

@@ -62,8 +62,32 @@ pnpm add eva-css-fluid
 yarn add eva-css-fluid
 ```
 
+**Migrating from another framework?** See the [Migration Guide](./MIGRATION.md) for detailed instructions.
+
 ## 🚀 Quick Start
 
+### New Project (Recommended)
+
+Get started instantly with a fully configured project:
+
+```bash
+npm init eva-css my-project
+cd my-project
+npm install
+npm run dev
+```
+
+This scaffolds a complete EVA CSS project with:
+- ✅ Pre-configured `eva.config.cjs`
+- ✅ Example HTML and SCSS files
+- ✅ Build scripts with purge support
+- ✅ Ready to customize with your design sizes
+
+**Choose from 3 templates:**
+- **Minimal** - Variables only, no utilities
+- **Utility** - Full utility classes (recommended)
+- **Full** - Everything + examples + theme switching
+
 ### Using Pre-built CSS
 
 ```html
@@ -72,13 +96,72 @@ yarn add eva-css-fluid
 
 ### Using SCSS with Default Configuration
 
+**Simple import** (Sass automatically finds the package in node_modules):
+
 ```scss
 @use 'eva-css-fluid';
 ```
 
+**Or with explicit path** (if needed):
+
+```scss
+@use 'eva-css-fluid/src' as *;
+```
+
+**Compilation** (no --load-path needed!):
+
+```bash
+# Simple - Sass finds the package automatically
+npx sass styles/main.scss:styles/main.css
+
+# Or with older Sass versions
+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!** Simply change the `$sizes` to match your Figma design:
+**This is the main feature of EVA CSS!** You can configure EVA CSS in two ways:
+
+#### Option 1: JSON Configuration (Recommended)
+
+Create `eva.config.cjs` in your project root:
+
+```javascript
+// eva.config.cjs
+module.exports = {
+  sizes: [4, 8, 16, 32, 64, 128],        // 👈 Change these to YOUR design sizes!
+  fontSizes: [14, 16, 20, 24, 32],       // 👈 Change these to YOUR font sizes!
+  buildClass: true,
+  pxRemSuffix: false
+};
+```
+
+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:
+
+```scss
+@use 'eva-css-fluid';
+```
+
+And build with the integrated script:
+
+```bash
+npm run build
+# Configuration is automatically loaded from eva.config.cjs or package.json
+```
+
+#### Option 2: SCSS Variables
 
 ```scss
 // Example: Sizes extracted from Figma design
@@ -108,6 +191,86 @@ yarn add eva-css-fluid
 
 ## 🎨 Configuration Options
 
+### JSON Configuration (eva.config.cjs or package.json)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sizes` | `number[]` | `[4, 8, 12, 16, ...]` | Available fluid size values (must include 16) |
+| `fontSizes` | `number[]` | `[12, 14, 16, ...]` | Available font sizes |
+| `buildClass` | `boolean` | `true` | Generate utility classes or variables only |
+| `pxRemSuffix` | `boolean` | `false` | Add px/rem static values for debugging |
+| `nameBySize` | `boolean` | `true` | Use size values in variable names |
+| `customClass` | `boolean` | `false` | Enable custom class filtering |
+| `classConfig` | `object` | `{}` | Map of properties to sizes for custom classes |
+| `debug` | `boolean` | `false` | Show configuration summary during compilation |
+| **`theme.name`** | `string` | `'eva'` | Theme name (CSS class: `.theme-{name}`) |
+| **`theme.colors`** | `object` | See below | Theme colors (HEX or OKLCH) |
+| **`theme.lightMode`** | `object` | `{lightness:96.4, darkness:6.4}` | Light mode configuration |
+| **`theme.darkMode`** | `object` | `{lightness:5, darkness:95}` | Dark mode configuration |
+| **`theme.autoSwitch`** | `boolean` | `false` | Auto-switch based on prefers-color-scheme |
+| `purge.enabled` | `boolean` | `false` | Enable CSS purging/tree-shaking |
+| `purge.content` | `string[]` | `['**/*.{html,js,...}']` | Files to scan for used classes |
+| `purge.css` | `string` | `'dist/eva.css'` | Input CSS file to purge |
+| `purge.output` | `string` | `'dist/eva-purged.css'` | Output path for purged CSS |
+| `purge.safelist` | `string[]` | `['theme-', ...]` | Classes/patterns to always keep |
+
+#### Theme Colors Configuration
+
+Define your theme colors in HEX (auto-converted to OKLCH) or OKLCH format:
+
+```javascript
+// eva.config.cjs
+module.exports = {
+  theme: {
+    name: 'myapp',
+    colors: {
+      // HEX format (from Figma, design tools, etc.)
+      brand: '#ff5733',    // Automatically converted to OKLCH
+      accent: '#7300ff',
+      extra: '#ffe500',
+
+      // Or OKLCH format (for precise control)
+      dark: { lightness: 20, chroma: 0.05, hue: 200 },
+      light: { lightness: 95, chroma: 0.01, hue: 200 }
+    },
+    lightMode: {
+      lightness: 96.4,   // Light background
+      darkness: 6.4      // Dark text
+    },
+    darkMode: {
+      lightness: 5,      // Dark background
+      darkness: 95       // Light text
+    },
+    autoSwitch: false    // Manual toggle with .toggle-theme class
+  }
+};
+```
+
+**Available colors:** `brand`, `accent`, `extra`, `dark`, `light`
+
+**Color formats:**
+- **HEX**: `"#ff5733"` - Automatically converted via eva-colors
+- **OKLCH**: `{ lightness: 68, chroma: 0.21, hue: 33.69 }`
+
+**Usage in HTML:**
+
+```html
+<body class="current-theme theme-myapp">
+  <h1 class="_c-brand">Hello World</h1>
+
+  <button onclick="document.body.classList.toggle('toggle-theme')">
+    Toggle Dark Mode
+  </button>
+</body>
+```
+
+**Configuration Priority:**
+1. JSON config file (`eva.config.cjs` or `eva.config.js`)
+2. package.json `"eva"` key
+3. SCSS `@use ... with ()` variables
+
+### SCSS Variables (when using @use with)
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `$sizes` | `4, 8, 12, 16, 24, 32, 48, 64, 96, 128` | Available fluid size values |
@@ -115,7 +278,22 @@ yarn add eva-css-fluid
 | `$build-class` | `true` | Generate utility classes (`true`) or variables only (`false`) |
 | `$px-rem-suffix` | `false` | Add px/rem static values for debugging |
 | `$name-by-size` | `true` | Use size values in variable names |
-| `$custom-class` | `false` | Enable custom class generation |
+| `$custom-class` | `false` | Enable custom class filtering |
+| `$class-config` | `()` | Map of properties to sizes when `$custom-class: true` |
+| `$debug` | `false` | Show class generation summary during compilation |
+
+### CLI Commands
+
+```bash
+# Validate your configuration
+npx eva-css validate
+
+# Generate SCSS variables from JSON config
+npx eva-css generate
+
+# Get help
+npx eva-css help
+```
 
 ## 💡 Usage Examples
 
@@ -144,6 +322,83 @@ yarn add eva-css-fluid
 }
 ```
 
+### Custom Class Mode (`$custom-class: true`)
+
+Generate only specific classes to reduce CSS output size:
+
+```scss
+@use 'eva-css-fluid/src' as * with (
+  $sizes: (24, 50, 100),
+  $custom-class: true,
+  $class-config: (
+    w: (50, 100),      // Only .w-50 and .w-100
+    px: (24,),         // Only .px-24 (note trailing comma)
+    g: (24, 50)        // Only .g-24 and .g-50
+  )
+);
+```
+
+This generates only the specified classes, perfect for production builds or when you need fine control over output size.
+
+### Pre-configured Entry Points
+
+EVA CSS provides multiple entry points for different use cases:
+
+```scss
+// Full framework (default) - Everything included
+@use 'eva-css-fluid';
+
+// Variables only - Just CSS variables, no utility classes
+@use 'eva-css-fluid/variables';
+
+// Core framework - Variables + reset + typography, no utilities
+@use 'eva-css-fluid/core';
+
+// Colors only - Just the OKLCH color system
+@use 'eva-css-fluid/colors';
+```
+
+**When to use each:**
+- **Default** (`eva-css-fluid`): Full-featured projects with utility classes
+- **Variables** (`eva-css-fluid/variables`): Building custom components
+- **Core** (`eva-css-fluid/core`): Foundation + custom utilities
+- **Colors** (`eva-css-fluid/colors`): Adding EVA colors to existing projects
+
+### Debug Mode
+
+Enable debug mode to see a summary of your configuration during compilation:
+
+```scss
+@use 'eva-css-fluid' with (
+  $sizes: (16, 24, 50, 100),
+  $debug: true  // ← Shows configuration summary
+);
+```
+
+**Output example:**
+```
+╔══════════════════════════════════════════════════════════════
+║ EVA CSS - Configuration Summary
+╠══════════════════════════════════════════════════════════════
+║ Sizes: 16, 24, 50, 100
+║ Total sizes: 4
+║ Font sizes: 16, 24
+║ Total font sizes: 2
+╠══════════════════════════════════════════════════════════════
+║ Build Configuration:
+║   - Build classes: true
+║   - Custom class mode: false
+║   - Px/Rem suffix: false
+║   - Name by size: true
+╠══════════════════════════════════════════════════════════════
+║ Estimated Utility Classes:
+║   - Size properties: ~256 classes
+║   - Available properties: w, mw, h, p, px, pr, py, br, mb, mr, ml, mt, pt, pb, g, gap
+╚══════════════════════════════════════════════════════════════
+```
+
+Perfect for understanding what's being generated and optimizing your configuration!
+
 ## 🎨 Fluid Scaling
 
 EVA CSS uses modern CSS `clamp()` for fluid scaling:
@@ -266,12 +521,64 @@ npx sass my-project.scss:my-project.css
 
 **The magic:** All sizes scale fluidly across viewport sizes using `clamp()` - no media queries needed!
 
+## 🗜️ Production Optimization (Tree-shaking)
+
+EVA CSS includes automatic CSS purging to remove unused classes in production builds.
+
+### Enable in Configuration
+
+```javascript
+// eva.config.cjs
+module.exports = {
+  sizes: [16, 24, 32, 64],
+  fontSizes: [16, 24, 32],
+  purge: {
+    enabled: true,                          // Enable purging
+    content: ['src/**/*.{html,js,jsx,tsx}'], // Files to scan
+    css: 'dist/eva.css',                    // Input CSS
+    output: 'dist/eva-purged.css',          // Output CSS
+    safelist: ['theme-', 'current-']        // Classes to keep
+  }
+};
+```
+
+### Build with Purge
+
+```bash
+# Build with purge (if enabled in config)
+npm run build
+
+# Or force purge via CLI flag
+npm run build:purge
+```
+
+**Results:** Typically reduces CSS file size by 60-90% depending on usage.
+
+### Manual Purge with eva-purge
+
+For more control, use the standalone `eva-purge` package:
+
+```bash
+# Install
+npm install --save-dev eva-css-purge
+
+# Run purge
+npx eva-purge --css dist/eva.css --content "src/**/*.html"
+
+# Or use eva.config.cjs
+npx eva-purge --config eva.config.cjs
+```
+
+See [eva-purge documentation](https://www.npmjs.com/package/eva-css-purge) for more options.
+
 ## 🛠️ Build from Source
 
 ```bash
 cd packages/eva-css
-npm run build        # Build expanded CSS
+npm run build        # Build with config (includes purge if enabled)
 npm run build:min    # Build minified CSS
+npm run build:purge  # Build with purge (force)
+npm run build:sass   # Build without config (pure SCSS)
 npm run watch        # Watch mode for development
 ```