npm package: @iltchenko/acss-framework
Description: Production-ready, multi-application CSS framework with dynamic customization capabilities
Author: ACSS Framework Team
Latest version: 1.0.0-beta.1

# ACSS Framework 🎨

> A production-ready, atomic CSS framework with dynamic customization capabilities built on UnoCSS

[![Beta Release](https://img.shields.io/badge/version-1.0.0--beta.1-orange.svg)](https://github.com/iltchenko/ACSS-inspired-UnoCSS-system/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Framework Agnostic](https://img.shields.io/badge/Framework-Agnostic-green.svg)](#framework-integration)
[![WCAG AA](https://img.shields.io/badge/WCAG-AA-green.svg)](#accessibility)

> **🚧 Beta Release**: This is a beta version for community testing and feedback. [Join our beta testing program!](./BETA_TESTING_GUIDE.md)

## 🎉 Beta Release Highlights

This beta release introduces the complete ACSS Framework ecosystem, ready for community testing and feedback.

### What's New in Beta
- **🎨 Dynamic Theme Engine**: Real-time theme customization with CSS custom properties
- **🖼️ Visual Theme Editor**: Interactive theme customization interface
- **🌐 Framework Integration**: React, Vue, Svelte, and vanilla JavaScript support
- **⚡ Performance Optimized**: Minimal bundle size with tree-shaking support
- **♿ Accessibility First**: WCAG 2.1 AA compliant with screen reader support
- **📱 Responsive Design**: Mobile-first approach with fluid typography
- **🔧 TypeScript Support**: Full type definitions and IntelliSense support

## ✨ Features

- 🎨 **Dynamic Theme System** - Runtime theme customization with CSS variables
- 🧩 **Modular Presets** - Typography, layout, components, animations, and utilities
- 🎛️ **Visual Theme Editor** - Live preview and export functionality
- 📱 **Container Queries** - Modern responsive design patterns
- 🔤 **Fluid Typography** - Mathematical scaling with CSS clamp()
- 🌙 **Dark Mode** - Built-in light/dark theme support
- 📦 **Tree Shakable** - Optimized bundle sizes with modern exports
- 🔧 **TypeScript** - Full type safety and IntelliSense support

## 🚀 Quick Start

### Installation

```bash
# Install the beta version
npm install @acss/framework@beta

# Or with yarn
yarn add @acss/framework@beta

# Or with pnpm
pnpm add @acss/framework@beta
```

### Basic Setup

```typescript
// uno.config.ts
import { defineConfig } from 'unocss'
import { presetACSSFramework } from '@acss/framework'

export default defineConfig({
  presets: [
    presetACSSFramework({
      // Optional configuration
      features: {
        fluidTypography: true,
        containerQueries: true,
        darkMode: true
      }
    })
  ]
})
```

### Using with CSS

```css
/* Import base styles */
@import '@acss/framework/css';

/* Your custom styles */
.my-component {
  @apply text-lg font-semibold text-primary-600;
}
```

## 📖 Documentation

### Core Concepts

- **[Getting Started](docs/getting-started.md)** - Installation and basic setup
- **[Theme System](docs/theme-system.md)** - Understanding themes and customization
- **[Design Tokens](docs/design-tokens.md)** - Primitive, semantic, and component tokens
- **[Presets](docs/presets-overview.md)** - Modular preset system overview

### Presets

- **[Typography Preset](docs/typography-preset.md)** - Fluid typography and text utilities
- **[Layout Preset](docs/layout-preset.md)** - Grid, flexbox, and container queries
- **[Component Preset](docs/component-preset.md)** - Pre-built component styles
- **[Animation Preset](docs/animation-preset.md)** - Transitions and motion utilities
- **[Utility Preset](docs/utility-preset.md)** - Helper classes and patterns

### Advanced Features

- **[Theme Editor](docs/theme-editor.md)** - Visual theme customization
- **[Runtime Customization](docs/runtime-customization.md)** - Dynamic theme changes
- **[Container Queries](docs/container-queries.md)** - Modern responsive design
- **[Fluid Typography](docs/fluid-typography.md)** - Mathematical scaling

### Integration Guides

- **[React Integration](docs/integrations/react.md)** - Setup with React and Next.js
- **[Vue Integration](docs/integrations/vue.md)** - Setup with Vue and Nuxt
- **[Svelte Integration](docs/integrations/svelte.md)** - Setup with Svelte and SvelteKit
- **[Vite Integration](docs/integrations/vite.md)** - Setup with Vite
- **[Webpack Integration](docs/integrations/webpack.md)** - Setup with Webpack

## 🎨 Theme Editor

The ACSS Framework includes a powerful visual theme editor for real-time customization:

```typescript
import { ThemeEditor } from '@acss/framework/editor'

const editor = new ThemeEditor({
  container: '#theme-editor',
  theme: myTheme,
  onThemeChange: (newTheme) => {
    // Apply theme changes
    applyTheme(newTheme)
  }
})
```

## 🏗️ Architecture

The framework is built with a modular architecture:

```
@acss/framework
├── Core Theme Engine     # Dynamic theme system
├── Modular Presets      # Typography, layout, components
├── Visual Editor        # Theme customization UI
├── Design Tokens        # Primitive, semantic, component
└── Utilities           # Helper functions and validation
```

## 📦 Package Exports

```typescript
// Main framework
import { presetACSSFramework } from '@acss/framework'

// Individual presets
import { typographyPreset } from '@acss/framework/presets'

// Theme engine
import { ThemeEngine } from '@acss/framework/theme-engine'

// Visual editor
import { ThemeEditor } from '@acss/framework/editor'

// CSS styles
import '@acss/framework/css'
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

Built with [UnoCSS](https://unocss.dev/) and inspired by atomic CSS methodologies.