zeus-css 1.0.4 → 1.0.6

package/README.md

@@ -10,32 +10,48 @@ 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`):
+### 1. Use the default theme (no build step)
+If the shipped defaults are fine as-is, just import the pre-compiled stylesheet in your entrypoint (e.g., `layout.tsx`, `_app.tsx` or `main.tsx`):
 
 ```typescript
 import 'zeus-css/dist/zeus.css';
 ```
 
-### 2. Generate Your Local Config
-Run the init command in your project root (you'll see a reminder for this after `npm install` too):
+> `dist/zeus.css` is compiled at publish time and always contains the framework defaults. It cannot reflect local customization — for that, use your own theme build in step 2.
+
+### 2. Customize it
+Run the init command in the folder you want the config files in (you'll see a reminder for this after `npm install` too):
 
 ```bash
 npx zeus-css init
 ```
 
-This creates `zeus.config.scss` and `zeus.customize.scss` directly in your project — not buried in `node_modules` — so you can edit them like any other file. Skip this step only if you're happy with the default theme as-is. Override colors, spacing, fonts, and more using OKLCH:
+This drops four files into that folder — not buried in `node_modules`:
+
+| File | Purpose |
+| --- | --- |
+| `zeus.config.scss` | **Edit this.** Feature toggles, breakpoints, layout engine settings. |
+| `zeus.customize.scss` | **Edit this.** Design tokens — colors, typography, spacing, shadows. |
+| `zeus.scss` | Generated bridge. Import it in `.module.scss` files for tokens/mixins. Emits no CSS. |
+| `zeus.theme.scss` | Generated entry point. Compile it to get your themed global stylesheet. |
+
+Edit your colors in `zeus.customize.scss` 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;
+```
+
+Then compile `zeus.theme.scss` and link **that** output instead of `zeus-css/dist/zeus.css`:
 
-@forward "zeus-css/scss/zeus.scss";
+```bash
+sass --load-path=node_modules zeus.theme.scss zeus.theme.css
 ```
 
+Re-run this command after any edit to `zeus.config.scss` / `zeus.customize.scss`. Running `npx zeus-css init` again never overwrites files you already have.
+
 ### 3. Use CSS Variables in CSS Modules
 Thanks to the framework's token generation, you can natively use the fluid CSS variables everywhere:
 
@@ -54,6 +70,13 @@ Thanks to the framework's token generation, you can natively use the fluid CSS v
 }
 ```
 
+### Compiling with the `sass` CLI directly (no bundler)
+Bundlers like Vite and Webpack resolve `@use "zeus-css/..."` automatically. The plain `sass` CLI does not — pass `--load-path=node_modules` or it will fail with `Can't find stylesheet to import`:
+
+```bash
+sass --load-path=node_modules your-file.scss your-file.css
+```
+
 ## ⚠️ 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.
 

package/bin/init.js

@@ -6,36 +6,43 @@ 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 themeTargetPath = path.join(projectRoot, 'zeus.theme.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);
-}
+// Checked per-file rather than all-or-nothing: a project initialized by an
+// older version has no zeus.theme.scss, and an all-or-nothing guard would
+// skip it forever on re-run. Generated entry points (zeus.scss/zeus.theme.scss)
+// are safe to refresh; the two files the developer edits are never touched
+// once they exist.
+const writeIfMissing = (targetPath, produce, label) => {
+  if (fs.existsSync(targetPath)) {
+    console.log('⏭️  ' + label + ' already exists — leaving your copy untouched.');
+    return;
+  }
+  produce();
+  console.log('✅ Created ' + label);
+};
 
 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');
+  writeIfMissing(
+    configTargetPath,
+    () => fs.copyFileSync(configSource, configTargetPath),
+    'zeus.config.scss'
+  );
+  writeIfMissing(
+    customizeTargetPath,
+    () => fs.copyFileSync(customizeSource, customizeTargetPath),
+    '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 (
+  // Shared "with (...)" body — passes every local override into whichever
+  // framework entry point is being configured below.
+  const configArgs = `
   // 1. Config Variables
   $zeus-enable-responsive-classes: localConfig.$zeus-enable-responsive-classes,
   $zeus-enable-animation-classes: localConfig.$zeus-enable-animation-classes,
@@ -70,20 +77,71 @@ try {
   $zeus-z-index: localCustomize.$zeus-z-index,
   $zeus-custom-vars: localCustomize.$zeus-custom-vars,
   $zeus-button-variants: localCustomize.$zeus-button-variants
-);
+`;
+
+  // 2. Generate the Bridge file — configured tokens/mixins/functions for
+  // .module.scss files. Emits zero CSS on its own (see zeus-css/scss/zeus.scss).
+  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.
+//
+// No CSS is emitted here — use this in component .module.scss files for
+// tokens/mixins/functions. For the actual compiled global stylesheet with
+// your overrides baked in, compile zeus.theme.scss instead (see below).
+
+@use "./zeus.config.scss" as localConfig;
+@use "./zeus.customize.scss" as localCustomize;
+
+@use "zeus-css/scss/zeus.scss" with (${configArgs});
 
 // 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!');
-  
+  writeIfMissing(
+    bridgeTargetPath,
+    () => fs.writeFileSync(bridgeTargetPath, bridgeContent, 'utf8'),
+    'zeus.scss (bridge)'
+  );
+
+  // 3. Generate the Theme file — same configuration, but through the
+  // CSS-emitting foundation entry point. Compile this instead of linking
+  // zeus-css/dist/zeus.css if you want your overrides to actually show up.
+  const themeContent = `// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Theme Entry Point                             ║
+// ║  Auto-generated by zeus-css init                             ║
+// ╚══════════════════════════════════════════════════════════════╝
+// Compile THIS file to get your global stylesheet with your local
+// zeus.config.scss / zeus.customize.scss overrides baked in — the
+// precompiled zeus-css/dist/zeus.css always ships with the framework
+// defaults and never sees your local edits.
+//
+//   sass --load-path=node_modules zeus.theme.scss zeus.theme.css
+//
+// Then link zeus.theme.css instead of zeus-css/dist/zeus.css.
+
+@use "./zeus.config.scss" as localConfig;
+@use "./zeus.customize.scss" as localCustomize;
+
+@use "zeus-css/scss/foundation/foundation.scss" with (${configArgs});
+`;
+
+  writeIfMissing(
+    themeTargetPath,
+    () => fs.writeFileSync(themeTargetPath, themeContent, 'utf8'),
+    'zeus.theme.scss'
+  );
+
   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('1. For component .module.scss files, use the bridge (no CSS emitted):');
   console.log('   @use "./zeus.scss" as *;');
-  console.log('2. Edit zeus.config.scss or zeus.customize.scss to update the framework globally.');
+  console.log('2. For your actual themed stylesheet, compile zeus.theme.scss and link its output instead of zeus-css/dist/zeus.css:');
+  console.log('   sass --load-path=node_modules zeus.theme.scss zeus.theme.css');
+  console.log('3. Edit zeus.config.scss or zeus.customize.scss and recompile to update the framework globally.');
 } catch (e) {
   console.error('❌ Failed to extract Zeus config files', e);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeus-css",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "⚡ A Premium, Zero-Emission, Fluid-Scaling CSS Framework based on Sass SCSS Engine",
   "author": "Stavros Lazaris",
   "license": "MIT",

package/scss/foundation/foundation.scss

@@ -14,6 +14,13 @@
 // ║  .module.scss), this file outputs real CSS classes.           ║
 // ╚══════════════════════════════════════════════════════════════╝
 
+// Forwarded (not just used) so that an external consumer can configure the
+// framework directly through this entry point:
+//   @use "zeus-css/foundation" with ($zeus-colors: (...), ...);
+// Without this forward, foundation.scss loads zeus.config with its defaults
+// immediately, before any external `with (...)` could ever apply — silently
+// locking every token to the shipped defaults regardless of local overrides.
+@forward "../zeus.config";
 @use "../zeus.config" as config;
 @use "./core/design";
 @use "./core/engine";