zeus-css 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# ⚡ Zeus CSS
+
+A Premium, Zero-Emission, Fluid-Scaling CSS Framework based on Sass SCSS Engine.
+
+## Installation
+
+```bash
+npm install zeus-css
+```
+
+## Quick Start
+
+### 1. Import Global Foundation
+Import the pre-compiled global foundation (Reset, Variable pipeline, utility classes) in your application entrypoint (e.g., `layout.tsx`, `_app.tsx` or `main.tsx`):
+
+```typescript
+import 'zeus-css/dist/zeus.css';
+```
+
+### 2. Configure Your Custom Theme (Optional)
+Generate the configuration file by running the init command in your project root:
+
+```bash
+npx zeus-css init
+```
+
+This will create a `zeus.config.scss` in your project. You can override colors, spacing, fonts, and more using OKLCH:
+
+```scss
+// zeus.config.scss
+$zeus-colors: (
+  "primary": oklch(57.9% 0.232 259.6),
+  "secondary": oklch(74.7% 0.174 60.6)
+) !default;
+
+@forward "zeus-css/scss/zeus.scss";
+```
+
+### 3. Use CSS Variables in CSS Modules
+Thanks to the framework's token generation, you can natively use the fluid CSS variables everywhere:
+
+```scss
+@use "zeus-css/scss/zeus.scss" as *;
+
+.card {
+  padding: var(--space-md) var(--space-lg);
+  background: var(--color-background);
+  border-radius: var(--border-radius-md);
+
+  /* Use the engine mixins for custom breakpoints */
+  @include screen-above(lg) {
+    border-radius: var(--border-radius-lg);
+  }
+}
+```
+
+## ⚠️ Optimizing for Production (Crucial)
+Zeus CSS ships with thousands of utility classes to give you absolute freedom during development. For production builds, you **must** use PurgeCSS to remove unused selectors and keep your CSS payload tiny.
+
+Example `postcss.config.js` for Next.js / Vite:
+```javascript
+module.exports = {
+  plugins: [
+    ['@fullhuman/postcss-purgecss', {
+      content: [
+          './pages/**/*.{js,jsx,ts,tsx}',
+          './components/**/*.{js,jsx,ts,tsx}',
+          './src/**/*.{js,jsx,ts,tsx}'
+      ],
+      defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || []
+    }]
+  ]
+}
+```
+
+## Features
+
+- **Fluid Linear Interpolation Engine**: Mathematical clamp generator for automatic responsive font sizes and spacing without media-query soup.
+- **Recursive Token Pipeline**: Automatically traverses and transforms complex Sass maps into CSS Custom Properties.
+- **CSS @property Type Safety**: Native browser-level type-safety for key tokens.
+- **Zero-Emission SCSS API**: Uses Sass `@forward` to expose core design tools without emitting a single duplicate byte of CSS.

package/bin/init.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const projectRoot = process.cwd();
+const configTargetPath = path.join(projectRoot, 'zeus.config.scss');
+const customizeTargetPath = path.join(projectRoot, 'zeus.customize.scss');
+const bridgeTargetPath = path.join(projectRoot, 'zeus.scss');
+
+const configSource = path.join(__dirname, '..', 'scss', 'zeus.config.scss');
+const customizeSource = path.join(__dirname, '..', 'scss', 'zeus.customize.scss');
+
+console.log('⚡ Initializing Zeus CSS Configuration (Eject Mode)...');
+
+if (fs.existsSync(configTargetPath) || fs.existsSync(bridgeTargetPath)) {
+  console.log('⚠️  Zeus config files already exist in this directory. Skipping.');
+  process.exit(0);
+}
+
+try {
+  // 1. Copy original zeus.config.scss and zeus.customize.scss
+  fs.copyFileSync(configSource, configTargetPath);
+  fs.copyFileSync(customizeSource, customizeTargetPath);
+  console.log('✅ Copied zeus.config.scss');
+  console.log('✅ Copied zeus.customize.scss');
+
+  // 2. Generate the Bridge file
+  const bridgeContent = `// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Bridge Entry Point                            ║
+// ║  Auto-generated by zeus-css init                             ║
+// ╚══════════════════════════════════════════════════════════════╝
+// This file injects your local configurations into the framework!
+// Do not edit this file unless you add/remove configuration keys.
+
+@use "./zeus.config.scss" as localConfig;
+@use "./zeus.customize.scss" as localCustomize;
+
+@use "zeus-css/scss/zeus.scss" with (
+  // 1. Config Variables
+  $zeus-enable-responsive-classes: localConfig.$zeus-enable-responsive-classes,
+  $zeus-enable-animation-classes: localConfig.$zeus-enable-animation-classes,
+  $zeus-enable-grid-system: localConfig.$zeus-enable-grid-system,
+  $zeus-enable-shadow-classes: localConfig.$zeus-enable-shadow-classes,
+  $zeus-enable-color-utilities: localConfig.$zeus-enable-color-utilities,
+  $zeus-enable-property-registration: localConfig.$zeus-enable-property-registration,
+  $zeus-use-prefix: localConfig.$zeus-use-prefix,
+  $zeus-class-prefix: localConfig.$zeus-class-prefix,
+  $zeus-version: localConfig.$zeus-version,
+  $zeus-container-bounds: localConfig.$zeus-container-bounds,
+  $zeus-root-font-size: localConfig.$zeus-root-font-size,
+  $zeus-focus-ring: localConfig.$zeus-focus-ring,
+  $zeus-outer-max-width: localConfig.$zeus-outer-max-width,
+  $zeus-breakpoints: localConfig.$zeus-breakpoints,
+  $zeus-viewports: localConfig.$zeus-viewports,
+  $zeus-viewport-gutter: localConfig.$zeus-viewport-gutter,
+  $zeus-outer-padding: localConfig.$zeus-outer-padding,
+  $zeus-column-gaps: localConfig.$zeus-column-gaps,
+
+  // 2. Customize Variables (Tokens)
+  $zeus-colors: localCustomize.$zeus-colors,
+  $zeus-font-family: localCustomize.$zeus-font-family,
+  $zeus-typography: localCustomize.$zeus-typography,
+  $zeus-space: localCustomize.$zeus-space,
+  $zeus-border-radius: localCustomize.$zeus-border-radius,
+  $zeus-border-line: localCustomize.$zeus-border-line,
+  $zeus-icon-size: localCustomize.$zeus-icon-size,
+  $zeus-shadows: localCustomize.$zeus-shadows,
+  $zeus-button-sizes: localCustomize.$zeus-button-sizes,
+  $zeus-base-colors: localCustomize.$zeus-base-colors,
+  $zeus-z-index: localCustomize.$zeus-z-index,
+  $zeus-custom-vars: localCustomize.$zeus-custom-vars,
+  $zeus-button-variants: localCustomize.$zeus-button-variants
+);
+
+// Expose the configured framework so you can import it elsewhere
+@forward "zeus-css/scss/zeus.scss";
+`;
+
+  fs.writeFileSync(bridgeTargetPath, bridgeContent, 'utf8');
+  console.log('✅ Created zeus.scss (Bridge) successfully!');
+  
+  console.log('\n🚀 Zeus CSS is fully ejected and ready!');
+  console.log('Next steps:');
+  console.log('1. Import your local bridge in your SCSS modules:');
+  console.log('   @use "./zeus.scss" as *;');
+  console.log('2. Edit zeus.config.scss or zeus.customize.scss to update the framework globally.');
+} catch (e) {
+  console.error('❌ Failed to extract Zeus config files', e);
+}