npm - @howssatoshi/quantumcss - Versions diffs - 1.1.0 → 1.3.0 - Mend

@howssatoshi/quantumcss 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +42 -436
package/dist/quantum.css +1086 -394
package/dist/quantum.min.css +4120 -1
package/package.json +3 -2
package/src/cli.js +52 -0
package/src/defaults.js +2 -2
package/src/generator.js +65 -6
package/src/styles/quantum-animations.css +73 -0
package/src/styles/quantum-components.css +42 -4
package/src/styles/quantum.css +57 -3
package/src/styles/starlight-ui.css +47 -4

package/README.md CHANGED Viewed

@@ -1,486 +1,92 @@
 # Quantum CSS - Next-Generation Utility Framework
-![Quantum CSS](https://img.shields.io/badge/Quantum%20CSS-v1.0.0-blue)
+![Quantum CSS](https://img.shields.io/badge/Quantum%20CSS-v1.3.0-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![Bundle Size](https://img.shields.io/badge/bundle%20size-6.2KB-brightgreen)
+![Bundle Size](https://img.shields.io/badge/bundle%20size-15KB-brightgreen)
-A modern, performance-optimized utility-first CSS framework with semantic naming, component-aware utilities, and advanced CSS features.
+A modern, performance-optimized utility-first CSS framework with semantic naming, recursive component presets, and advanced cosmic effects.
 ## 🚀 Features
 ### Modern CSS Capabilities
-- **Container Queries** - Query container elements instead of viewport
-- **Logical Properties** - Use `margin-inline`, `padding-block`, etc.
-- **CSS Custom Properties** - Design tokens and CSS variables
-- **Modern Selectors** - `:where()`, `:is()`, and CSS nesting
-### Enhanced Utilities
-- **500+ Utility Classes** - Comprehensive coverage
-- **Starlight Aesthetics** - Ethereal design system with glassmorphism, atmospheric glows, and vibrant gradients
-- **Component Utilities** - Pre-built button, card, form components
-- **State Variants** - Hover, focus, active, disabled states
-- **Dark Mode** - Automatic and manual dark mode support
-- **Responsive Variants** - Mobile-first with container queries
+- **Recursive Component Presets** - Define custom components in config using existing utilities
+- **Cosmic Animation Library** - Advanced effects like parallax nebula drifts and orbit paths
+- **High Contrast Mode** - Native support for `prefers-contrast` and `forced-colors`
+- **JIT Dark Mode** - Dynamic generation of dark mode variants via `dark:` prefix
 ### Developer Experience
-- **Zero Configuration** - Works out of the box
+- **Advanced CLI Scaffolding** - Instantly generate pre-styled templates (Gaming, Blog, News, Shopping, Travel)
+- **Dynamic Documentation** - Generate a "Kitchen Sink" overview of your unique design tokens
 - **TypeScript Support** - Full type definitions
-- **Build Tools** - Custom build system with analysis
-- **Small Bundle Size** - 15KB gzipped, optimized for performance
+- **Zero Configuration** - Works out of the box
 ## 📦 Installation
 ```bash
-# npm
 npm install @howssatoshi/quantumcss
-# yarn
-yarn add @howssatoshi/quantumcss
-# pnpm
-pnpm add @howssatoshi/quantumcss
 ```
 ## 🎯 Quick Start
-### HTML Usage
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <link rel="stylesheet" href="dist/quantum.min.css">
-</head>
-<body>
-  <div class="container mx-auto p-6 space-y-4">
-    <h1 class="text-3xl font-bold text-primary mb-4">
-      Hello QuantumCSS!
-    </h1>
-    <button class="btn btn-primary hover:scale-105 transition-all">
-      Get Started
-    </button>
-  </div>
-</body>
-</html>
-```
-### CSS Import
-```css
-@import '@howssatoshi/quantumcss/dist/quantum.min.css';
-```
-## 🎨 Utility Classes
-### Layout
-```html
-<div class="container mx-auto px-4">
-  <div class="grid grid-cols-1 md:grid-cols-3 lg:grid-cols-12 gap-6">
-    <div class="lg:col-span-8 card">Main Content</div>
-    <div class="lg:col-span-4 card">Sidebar</div>
-  </div>
-</div>
-```
-### Typography
-```html
-<h1 class="text-4xl font-bold text-primary">Heading</h1>
-<p class="text-base text-neutral leading-relaxed">Paragraph text</p>
-<!-- Smart Typography: Large text sizes automatically include unitless line-heights -->
-<h2 class="text-5xl font-bold">Overlapping Fixed</h2>
-```
-### Colors
-```html
-<!-- JIT Color Resolution: Support for base names and opacity -->
-<div class="bg-primary/10 text-primary p-4 rounded-lg border border-primary">
-  <div class="text-secondary">Opacity and base color mapping</div>
-</div>
-```
-### Spacing
-```html
-<div class="m-4 p-6 mb-8">
-  <!-- Smart Spacing: space-y and space-x utilities for child elements -->
-  <div class="space-y-4">
-    <div class="py-2">Item 1</div>
-    <div class="py-2">Item 2</div>
-  </div>
-</div>
-```
-## 🧩 Component Utilities
-### Buttons
-```html
-<button class="btn btn-primary">Primary</button>
-<button class="btn btn-secondary btn-lg">Large</button>
-<button class="btn btn-outline">Outline</button>
-<button class="btn btn-ghost">Ghost</button>
-```
-### Forms
-```html
-<input type="text" class="input" placeholder="Enter text">
-<input type="email" class="input input-error" placeholder="Error state">
-<select class="input">
-  <option>Choose option</option>
-</select>
-```
-### Cards
-```html
-<div class="card">
-  <div class="card-header">
-    <h3 class="text-xl font-semibold">Card Title</h3>
-  </div>
-  <div class="card-body">
-    <p class="text-neutral">Card content goes here</p>
-  </div>
-  <div class="card-footer">
-    <button class="btn btn-primary btn-sm">Action</button>
-  </div>
-</div>
-```
-### Alerts
-```html
-<div class="alert alert-success">Success message</div>
-<div class="alert alert-warning">Warning message</div>
-<div class="alert alert-error">Error message</div>
-<div class="alert alert-info">Info message</div>
-```
-### Badges
-```html
-<!-- Enhanced Badges: Less rounded (0.375rem), 1px border, and glassmorphism compatible -->
-<span class="badge badge-primary">Primary</span>
-<span class="badge badge-secondary">Secondary</span>
-<span class="badge badge-success">Success</span>
-<span class="badge badge-warning">Warning</span>
-<span class="badge badge-error">Error</span>
-```
-## ✨ Starlight UI
-The Starlight theme provides a futuristic, ethereal design system inspired by modern AI interfaces and space aesthetics.
-### Key Features
-- **Glassmorphism**: Hardware-accelerated blur effects with improved composability (`.glass`).
-- **Atmospheric Glows**: Soft, colored shadows that simulate light sources (`.glow-blue`, `.glow-peach`).
-- **Vibrant Gradients**: Carefully crafted color transitions (`.bg-starlight`, `.text-gradient-starlight`).
-- **Premium Components**: Enhanced variants including theme-aware links and layering-friendly containers.
-### Example Usage
-```html
-<div class="glass p-8 rounded-2xl glow-blue border-l-4 border-primary">
-  <h2 class="text-starlight font-bold">Starlight Interface</h2>
-  <p class="text-muted">Experience the future of styling with smart composability.</p>
-  <button class="btn-starlight">
-    Launch
-  </button>
-</div>
-```
-## 📱 Responsive Design
-### Breakpoint Variants
-```html
-<div class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">
-  <!-- Responsive grid -->
-</div>
-```
-### Container Queries (Advanced)
-```html
-<div class="container" style="container-type: inline-size;">
-  <div class="container:grid container:grid-cols-2 container:p-6">
-    <!-- Container query responsive -->
-  </div>
-</div>
-```
-### Dark Mode
-```html
-<div class="bg-white dark:bg-gray-900 text-black dark:text-white">
-  <!-- Automatic dark mode support -->
-</div>
-```
-## 🎯 State Variants
-### Hover Effects
-```html
-<button class="btn btn-primary hover:bg-primary-600 hover:scale-105">
-  Hover me
-</button>
-<div class="card hover:shadow-lg hover:scale-105 transition-all">
-  <!-- Interactive card -->
-</div>
-```
-### Focus States
-```html
-<input class="input focus:ring-2 focus:ring-primary focus:border-primary">
-<button class="btn focus:outline-none focus:ring-2 focus:ring-primary">
-  Accessible button
-</button>
-```
-### Active States
-```html
-<button class="btn active:scale-95 active:bg-primary-700">
-  Press me
-</button>
+### CLI Scaffolding
+Quickly jumpstart your project with a premium template:
+```bash
+npx @howssatoshi/quantumcss scaffold gaming index.html
 ```
+*Available templates: `gaming`, `blog`, `news`, `shopping`, `travel`, `starlight`*
-### Disabled States
+### HTML Usage
 ```html
-<button class="btn disabled:opacity-50 disabled:cursor-not-allowed" disabled>
-  Disabled
+<button class="btn-starlight ani-float">
+  Launch Experience
 </button>
 ```
 ## ⚙️ Configuration
-### Basic Configuration
-Create `quantum.config.json`:
-```json
-{
-  "theme": {
-    "extend": {
-      "colors": {
-        "brand": "#3b82f6",
-        "accent": "#10b981"
-      },
-      "fontFamily": {
-        "display": ["Inter", "system-ui", "sans-serif"]
-      },
-      "spacing": {
-        "18": "4.5rem",
-        "88": "22rem"
-      }
-    }
-  },
-  "darkMode": "media"
-}
-```
-### Build Configuration
+### Component Presets
+Define your own components in `quantum.config.json`:
 ```json
 {
-  "content": [
-    "./src/**/*.{html,js,ts,jsx,tsx}"
-  ],
-  "presets": [
-    "modern-css"
-  ],
-  "plugins": [
-    "container-queries",
-    "component-utilities"
-  ]
+  "componentPresets": {
+    "btn-action": "btn-starlight px-8 py-3 rounded-xl hover:scale-105 transition",
+    "card-glass": "glass p-6 rounded-2xl border border-white/10 dark:bg-white/5"
+  }
 }
 ```
-## 🛠️ Build Tools
-### Development
-```bash
-# Watch for changes and rebuild
-npm run watch
-# Build for development (not minified)
-npm run build:dev
-# Generate JIT utilities from content
-npm run generate
-```
+## ✨ Cosmic Animations
-### Production
-```bash
-# Build minified CSS
-npm run build
+Bring your UI to life with space-inspired effects:
+- `.ani-nebula` - Ethereal drifting gradient backgrounds
+- `.ani-float` - Floating vertical motion
+- `.ani-twinkle` - Sparkling star effects
+- `.ani-orbit` - Circular orbital paths
+- `.ani-svg-draw` - Progressive path drawing for icons
-# Generate JIT utilities with custom output
-npx @howssatoshi/quantumcss dist/custom.css
-```
+## 🛠️ Build Tools
-### Build Analysis
+### Documentation
+Generate a live dashboard of your theme:
 ```bash
-# Analyze CSS output
-npm run analyze
-# Output includes:
-# - Selector count
-# - Property usage
-# - Utility class count
-# - Component class count
-# - Responsive variant usage
-# - Color palette analysis
-# - Breakpoint distribution
-```
-## 🎨 Customization
-### Adding Custom Colors
-```css
-:root {
-  --color-brand: #6366f1;
-  --color-brand-50: #eef2ff;
-  --color-brand-100: #e0e7ff;
-  /* ... rest of scale */
-}
-.brand-text { color: var(--color-brand); }
-.brand-bg { background-color: var(--color-brand); }
-```
-### Custom Spacing Scale
-```css
-:root {
-  --space-14: 3.5rem;
-  --space-72: 18rem;
-}
-.p-14 { padding: var(--space-14); }
-.m-72 { margin: var(--space-72); }
+npm run docs
 ```
+This creates `examples/kitchen-sink.html` with all your colors, spacing, presets, and animations.
-### Custom Animations
-```css
-@keyframes slideInFromLeft {
-  from {
-    transform: translateX(-100%);
-    opacity: 0;
-  }
-  to {
-    transform: translateX(0);
-    opacity: 1;
-  }
-}
-.animate-slide-left {
-  animation: slideInFromLeft 0.3s ease-out;
-}
-```
+### High Contrast Support
+QuantumCSS automatically optimizes contrast for accessibility when the user enables high contrast mode in their OS.
 ## 📊 Performance
-### Bundle Size Comparison
-- **QuantumCSS**: 15KB gzipped
-- **Bootstrap**: 25KB gzipped
-- **Bulma**: 20KB gzipped
-### Performance Features
-- **CSS Custom Properties** - Faster theme switching
-- **Optimized Selectors** - Minimal specificity
-- **Tree Shaking** - Only used classes included
-- **Container Queries** - Better performance than media queries
-- **Logical Properties** - Better performance than directional properties
-## 🧩 Advanced Components
-### Modal
-```html
-<div class="modal-overlay">
-  <div class="modal-content">
-    <div class="p-6">
-      <h2 class="text-2xl font-bold mb-4">Modal Title</h2>
-      <p class="text-neutral mb-6">Modal content</p>
-      <div class="flex gap-2">
-        <button class="btn btn-primary">Confirm</button>
-        <button class="btn btn-outline">Cancel</button>
-      </div>
-    </div>
-  </div>
-</div>
-```
-### Dropdown
-```html
-<div class="dropdown">
-  <button class="btn" onclick="toggleDropdown(this)">Menu</button>
-  <div class="dropdown-content">
-    <button class="dropdown-item">Item 1</button>
-    <button class="dropdown-item">Item 2</button>
-    <button class="dropdown-item">Item 3</button>
-  </div>
-</div>
-```
-### Tabs
-```html
-<div class="tab-list">
-  <button class="tab-button active">Tab 1</button>
-  <button class="tab-button">Tab 2</button>
-  <button class="tab-button">Tab 3</button>
-</div>
-<div class="tab-content">
-  <div class="tab-panel active">Content 1</div>
-  <div class="tab-panel">Content 2</div>
-  <div class="tab-panel">Content 3</div>
-</div>
-```
-### Accordion
-```html
-<div class="accordion-item">
-  <div class="accordion-header">
-    <span>Accordion Title</span>
-    <span class="accordion-icon">▼</span>
-  </div>
-  <div class="accordion-content">
-    Accordion content
-  </div>
-</div>
-```
-## 🎯 Best Practices
-### Performance Tips
-1. **Use Container Queries** for component-level responsiveness
-2. **Leverage CSS Custom Properties** for dynamic theming
-3. **Prefer Utility Classes** over custom CSS
-4. **Use Logical Properties** for internationalization
-5. **Optimize Bundle Size** with build analysis
-### Accessibility
-```html
-<!-- Accessible button -->
-<button class="btn focus:ring-2 focus:ring-primary focus:ring-offset-2">
-  Accessible Button
-</button>
-<!-- Screen reader only text -->
-<span class="sr-only">Hidden from sight, visible to screen readers</span>
-<!-- Semantic markup -->
-<main class="container mx-auto" role="main">
-  <h1 class="sr-only">Page title for screen readers</h1>
-</main>
-```
+### Bundle Size
+- **QuantumCSS Core**: ~15KB gzipped
+- **Optimized Selectors**: Minimal specificity for maximum performance
+- **Tree Shaking**: Only used utilities and presets are generated in JIT mode
 ## 🤝 Contributing
 We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-### Development Setup
-```bash
-git clone https://github.com/macroadster/quantumcss.git
-cd quantumcss
-npm install
-npm run watch
-```
 ## 📄 License
 MIT License - see [LICENSE](LICENSE) file for details.
-## 🔗 Links
-- **Documentation**: https://github.com/macroadster/quantumcss#readme
-- **GitHub**: https://github.com/macroadster/quantumcss
-- **NPM**: https://npmjs.com/package/@howssatoshi/quantumcss
-- **Discord**: https://discord.gg/quantumcss
----
-**QuantumCSS** - The future of utility-first CSS frameworks. Built with modern CSS, designed for modern web development. 🚀