rustyle-css 0.3.0

# Migration Guide: Rustyle 0.1.0 → 0.2.0

This guide will help you migrate your Rustyle 0.1.0 code to Rustyle 0.2.0.

## Overview

Rustyle 0.2.0 maintains backward compatibility for basic usage, but introduces many new features and improvements. Most existing code will continue to work, but we recommend migrating to take advantage of the new capabilities.

## Breaking Changes

### Minimal Breaking Changes

Rustyle 0.2.0 is designed to be backward compatible. The following changes may affect your code:

1. **Theme API** - The `Theme` struct now uses `DesignTokens` instead of individual color fields
2. **Some internal APIs** - Internal APIs have been refactored, but public APIs remain stable

## Migration Steps

### 1. Update Dependencies

```toml
[dependencies]
rustyle = "0.2.0"  # Updated from 0.1.0
leptos = "0.8.14"
```

### 2. Basic Style Macros (No Changes Required)

The basic `style!` macro works exactly the same:

```rust
// ✅ Works in both 0.1.0 and 0.2.0
let class = style! {
    .button {
        background-color: #007bff;
        color: white;
    }
};
```

### 3. Theme Migration

#### Old Way (0.1.0)
```rust
use rustyle::{Theme, apply_theme};

let theme = Theme::light();
apply_theme(&theme);
```

#### New Way (0.2.0) - Recommended
```rust
use rustyle::{Theme, apply_theme, DesignTokens};

// Option 1: Use default theme (same as before)
let theme = Theme::light();
apply_theme(&theme);

// Option 2: Use custom design tokens
let tokens = DesignTokens::default();
let theme = Theme::custom("my-theme", tokens);
apply_theme(&theme);

// Option 3: Multi-theme support
use rustyle::ThemeManager;
let mut manager = ThemeManager::new(Theme::light());
manager.add_theme(Theme::dark());
manager.switch_to("dark");
```

### 4. Using Design Tokens (New Feature)

Design tokens provide a centralized way to manage your design system:

```rust
use rustyle::DesignTokens;

// Use default tokens
let tokens = DesignTokens::default();

// Access token values
let primary_color = tokens.colors.primary.c500.clone();
let spacing_md = tokens.spacing.md.clone();

// Convert to CSS variables
let css_vars = tokens.to_css_vars();
```

### 5. Component Styles (New Feature)

Instead of writing manual CSS, use pre-built components:

#### Old Way (Manual CSS)
```rust
let class = style! {
    .button {
        background-color: #007bff;
        color: white;
        padding: 10px 20px;
        border-radius: 5px;
    }
};
```

#### New Way (Component Styles)
```rust
use rustyle::{ButtonStyle, Variant, Size};

let button = ButtonStyle::new(Variant::Primary, Size::Medium);
let css = button.to_css();
// Use css in your component
```

### 6. Reactive Styling (Enhanced)

#### Old Way (0.1.0)
```rust
// Basic reactive support
let class = style_signal! {
    .counter {
        font-size: 16px;
    }
};
```

#### New Way (0.2.0)
```rust
use leptos::*;
use rustyle::create_reactive_style;

#[component]
fn Counter(cx: Scope) -> impl IntoView {
    let (count, set_count) = create_signal(cx, 0);
    
    // Full signal integration
    let style = create_reactive_style(
        "padding: 10px;",
        vec![("font-size", count.map(|c| format!("{}px", c * 2 + 16)))],
    );
    
    view! { cx,
        <div style=style>
            <button on:click=move |_| set_count.update(|c| *c += 1)>
                "Count: " {count}
            </button>
        </div>
    }
}
```

### 7. Modern CSS Features (New)

#### View Transitions
```rust
use rustyle::view_transition;

view_transition! {
    .page {
        view-transition-name: main-content;
    }
}
```

#### Advanced Selectors
```rust
use rustyle::{HasSelector, IsSelector, WhereSelector};

let has_selector = HasSelector::new(".child");
let is_selector = IsSelector::new(vec![".button", ".link"]);
let where_selector = WhereSelector::new(vec![".card", ".panel"]);
```

### 8. Accessibility Features (New)

```rust
use rustyle::{register_focus_styles, register_reduced_motion, FocusStyle};

// Register focus styles
let focus_style = FocusStyle::new();
register_focus_styles(&focus_style);

// Register reduced motion support
register_reduced_motion();
```

### 9. Testing and Linting (New)

```rust
use rustyle::{CssAssertions, CssLinter, ContrastLinter};

// CSS assertions
assert!(CssAssertions::assert_contains_property(css, "color"));

// Linting
let results = CssLinter::lint(css);
for result in results {
    println!("{:?}: {}", result.severity, result.message);
}
```

## Feature Flags

Rustyle 0.2.0 introduces a `dev` feature for development tools:

```toml
[features]
dev = ["rustyle/dev"]
```

Enable it for:
- Hot Module Replacement (HMR)
- Debugging tools
- Style inspector

## Common Patterns

### Pattern 1: Design System Setup

```rust
use rustyle::{DesignTokens, Theme, apply_theme};

fn setup_design_system() {
    let tokens = DesignTokens::default();
    let theme = Theme::custom("app-theme", tokens);
    apply_theme(&theme);
}
```

### Pattern 2: Component with Variants

```rust
use rustyle::{ButtonStyle, Variant, Size, State};

fn create_button(variant: Variant, size: Size) -> String {
    ButtonStyle::new(variant, size)
        .state(State::Default)
        .to_css()
}
```

### Pattern 3: Responsive Design

```rust
use rustyle::{ResponsiveSpacing, Spacing, Length};

let responsive = ResponsiveSpacing::new(
    Spacing::all(Length::rem(1.0)),  // Mobile
    Some(Spacing::all(Length::rem(1.5))),  // Tablet
    Some(Spacing::all(Length::rem(2.0))),  // Desktop
);
```

## Troubleshooting

### Issue: Theme not applying

**Solution**: Make sure you call `apply_theme()` after creating the theme:

```rust
let theme = Theme::light();
apply_theme(&theme);  // Don't forget this!
```

### Issue: Components not styling correctly

**Solution**: Make sure you're calling `.to_css()` on component styles:

```rust
let button = ButtonStyle::new(Variant::Primary, Size::Medium);
let css = button.to_css();  // Get the CSS string
```

### Issue: Reactive styles not updating

**Solution**: Ensure you're using Leptos signals correctly and the `csr` feature is enabled:

```toml
[dependencies]
rustyle = { version = "0.2.0", features = ["csr"] }
```

## Need Help?

- Check the [README.md](README.md) for comprehensive documentation
- See the `examples/` directory for complete examples
- Open an issue on [GitHub](https://github.com/usvx/rustyle)

## Summary

Most Rustyle 0.1.0 code will work without changes in 0.2.0. The main benefits of migrating are:

1. **Design Tokens** - Centralized design system management
2. **Component Styles** - Pre-built, type-safe components
3. **Better Theming** - Multi-theme support with transitions
4. **Modern CSS** - Support for latest CSS features
5. **Accessibility** - Built-in a11y features
6. **Developer Tools** - HMR, debugging, linting

Take your time migrating - there's no rush! The old APIs will continue to work.