eva-css-fluid 1.0.4 → 2.0.5

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)