zeus-css 1.0.9 → 1.0.11

package/README.md

@@ -36,6 +36,16 @@ Always import it from a single **shared/root** entry point, never from an indivi
 
 **TypeScript:** `import 'zeus-css/dist/zeus.css'` needs *some* ambient `declare module '*.css'` to type-check. Next.js, Vite and Nuxt scaffolds already include this by default — nothing to do. If you're on a bare TypeScript setup and see `Cannot find module 'zeus-css/dist/zeus.css'`, running `npx zeus-css init` (step 2) creates `zeus-css-env.d.ts` for you automatically.
 
+> ⚠️ **Step 1 and Step 2 are mutually exclusive.** Use the default import
+> (`zeus-css/dist/zeus.css`) if you don't need custom theming. If you run
+> `npx zeus-css init` and customize your theme, **replace** the default
+> import with `import './zeus.theme.css'` — never use both together.
+>
+> ```text
+> No customization?  →  import 'zeus-css/dist/zeus.css'
+> Custom theme?       →  npx zeus-css init, compile, import './zeus.theme.css' (replaces the Step 1 import)
+> ```
+
 ### 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):
 

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "zeus-css",
-  "version": "1.0.9",
-  "description": "⚡ A Premium, Zero-Emission, Fluid-Scaling CSS Framework based on Sass SCSS Engine",
-  "author": "Stavros Lazaris",
-  "license": "MIT",
-  "homepage": "https://www.npmjs.com/package/zeus-css",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zeus-css/zeus-css-framework.git"
-  },
-  "bugs": {
-    "url": "https://github.com/zeus-css/zeus-css-framework/issues"
-  },
-  "main": "./dist/zeus.css",
-  "style": "./dist/zeus.css",
-  "bin": {
-    "zeus-css": "./bin/init.js"
-  },
-  "scripts": {
-    "postinstall": "node ./bin/postinstall.js"
-  },
-  "exports": {
-    ".": {
-      "sass": "./scss/zeus.scss",
-      "css": "./dist/zeus.css",
-      "default": "./dist/zeus.css"
-    },
-    "./foundation": "./scss/foundation/foundation.scss",
-    "./zeus": "./scss/zeus.scss",
-    "./config": "./scss/zeus.config.scss",
-    "./customize": "./scss/zeus.customize.scss",
-    "./dist/*": "./dist/*",
-    "./scss/*": "./scss/*",
-    "./bin/*": "./bin/*"
-  },
-  "files": [
-    "scss",
-    "dist",
-    "bin"
-  ],
-  "peerDependencies": {
-    "sass": "^1.60.0"
-  },
-  "keywords": [
-    "zeus",
-    "css",
-    "scss",
-    "sass",
-    "framework",
-    "fluid-design",
-    "design-tokens",
-    "type-safe"
-  ]
-}
+{
+  "name": "zeus-css",
+  "version": "1.0.11",
+  "description": "⚡ A Premium, Zero-Emission, Fluid-Scaling CSS Framework based on Sass SCSS Engine",
+  "author": "Stavros Lazaris",
+  "license": "MIT",
+  "homepage": "https://www.npmjs.com/package/zeus-css",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zeus-css/zeus-css-framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zeus-css/zeus-css-framework/issues"
+  },
+  "main": "./dist/zeus.css",
+  "style": "./dist/zeus.css",
+  "bin": {
+    "zeus-css": "./bin/init.js"
+  },
+  "scripts": {
+    "postinstall": "node ./bin/postinstall.js"
+  },
+  "exports": {
+    ".": {
+      "sass": "./scss/zeus.scss",
+      "css": "./dist/zeus.css",
+      "default": "./dist/zeus.css"
+    },
+    "./foundation": "./scss/foundation/foundation.scss",
+    "./zeus": "./scss/zeus.scss",
+    "./config": "./scss/zeus.config.scss",
+    "./customize": "./scss/zeus.customize.scss",
+    "./dist/*": "./dist/*",
+    "./scss/*": "./scss/*",
+    "./bin/*": "./bin/*"
+  },
+  "files": [
+    "scss",
+    "dist",
+    "bin"
+  ],
+  "peerDependencies": {
+    "sass": "^1.60.0"
+  },
+  "keywords": [
+    "zeus",
+    "css",
+    "scss",
+    "sass",
+    "framework",
+    "fluid-design",
+    "design-tokens",
+    "type-safe"
+  ]
+}

package/scss/API.md

@@ -15,16 +15,24 @@ this file wins.
 
 | Import | Emits CSS? | Use in |
 |---|---|---|
-| `@use "zeus-css/foundation";` | Yes — full compiled framework | App root, once |
+| `import "zeus-css/css";` | Yes — precompiled, default tokens only, not customizable | App root, no Sass pipeline |
+| `import "zeus-css/min";` | Yes — same as above, minified | App root, no Sass pipeline, production |
+| `@use "zeus-css/foundation";` | Yes — full compiled framework | App root, once, Sass pipeline |
 | `@use "zeus-css/zeus" as *;` | No — mixins/functions only | Every `.module.scss` |
 | `@use "zeus-css/config";` | No | Only if you need raw access to `$zeus-*` config variables |
 | `@use "zeus-css/customize";` | No | Only if you need raw access to `$zeus-colors` etc. without the rest of config |
 
+`zeus-css/css` and `zeus-css/min` are static builds of `foundation.scss` with
+default tokens baked in at publish time (`npm run build:css`) — they cannot
+reflect `zeus.customize.scss` overrides. Use one of the two SCSS entry points
+below instead if you need custom tokens.
+
 `package.json` → `files` is the authoritative list of what ships: the
-`foundation/**/*.scss` tree, the four entry files above, `zeus.tokens.json`,
-`llms.txt`, `cheatsheet.md`, `LICENSE`, `README.md`, `CHANGELOG.md`. Anything
-under `foundation/` not reachable through one of the two entry points (see
-§6) is an implementation detail even though the file ships.
+`foundation/**/*.scss` tree, the six entry points above (plus their compiled
+`dist/` output), `zeus.tokens.json`, `llms.txt`, `cheatsheet.md`, `LICENSE`,
+`README.md`, `CHANGELOG.md`. Anything under `foundation/` not reachable
+through `foundation` or `zeus` (see §6) is an implementation detail even
+though the file ships.
 
 ## 2. Config variables (`zeus.config.scss`, `zeus.customize.scss`)
 

package/scss/CHANGELOG.md

@@ -6,6 +6,20 @@ documented in [`API.md`](API.md).
 
 ## [Unreleased]
 
+## [1.0.11] — 2026-08-05
+
+### Fixed
+- **The published package's README (generated by `scripts/build-package.ts`,
+  not copied from this file) documented Step 1 (`zeus-css/dist/zeus.css`) and
+  Step 2 (`npx zeus-css init` + `zeus.theme.css`) with no statement that
+  they're mutually exclusive** — a dev following both in sequence ended up
+  with both imports in the same root layout. Added an explicit warning plus
+  a two-line flowchart between the two steps in that template, so the
+  generated README (and every future publish) states the replacement
+  relationship instead of leaving it implied.
+
+## [1.0.10] — 2026-08-05
+
 Published to npm as `zeus-css`. [`API.md`](API.md) documents the public API
 surface this changelog's semver contract is now binding against.
 
@@ -157,6 +171,14 @@ surface this changelog's semver contract is now binding against.
   `.`, `./config`, and the raw `./scss/*` passthrough — so three of the four
   documented specifiers failed to resolve against the published package.
   Explicit aliases for all four are now emitted.
+- **`zeus-css/css` and `zeus-css/min` were real, shipped exports
+  (`package.json` → `exports`) with no entry in README or `API.md` §1** — a
+  dev with no Sass pipeline had no documented way to just import the
+  precompiled CSS, and the two specifiers carried no semver contract despite
+  already being public. README now leads with them for the no-build-step
+  path; `API.md` §1 lists both, with a note that they're static builds of
+  `foundation.scss` with default tokens baked in and cannot reflect
+  `zeus.customize.scss` overrides.
 - `$zeus-outer-padding` was declared twice in `zeus.config.scss` — an older
   `(mobile, desktop)`-shaped default (used internally to auto-derive
   `$container-bounds`) and a newer `(floor, ceil)`-shaped default (the public

package/scss/README.md

@@ -46,9 +46,34 @@ absence costs placement, never functionality.
 npm install zeus-css
 ```
 
-## Two entry points
+No Sass pipeline and no customization needed? Import the precompiled CSS
+once, at your app root, and skip everything below about entry points and
+theming:
 
-Zeus ships two distinct ways to consume it — pick the right one per file.
+```tsx
+// app/layout.tsx
+import "zeus-css/css"; // or "zeus-css/dist/zeus.css" / "zeus-css/min" for the minified build
+```
+
+## Two ways to consume Zeus — pick one
+
+These are **mutually exclusive** at the app-root level. Never load both in
+the same project.
+
+| | No Sass pipeline | Sass pipeline (Next.js, Vite, webpack `sass-loader`) |
+|---|---|---|
+| **Import** | `zeus-css/css` (plain compiled CSS) | `@use "zeus-css/foundation"` |
+| **Customizable?** | No — ships the default token values baked in | Yes — edit `zeus.customize.scss` first (see [Theming your brand](#theming-your-brand)) |
+| **Use when** | You just want the framework as-is, no build step | You want your own brand colors/type/spacing |
+
+If you don't need custom theming, skip straight to
+[Install](#install) and use the plain CSS import. If you *do* need custom
+theming, use the SCSS entry point — the precompiled CSS can't reflect your
+overrides, since it was built once, at publish time, with the default tokens.
+
+## Two entry points (SCSS pipeline)
+
+Once you're on the SCSS path, Zeus exposes two distinct entry points — pick the right one per file.
 
 ### 1. Global stylesheet — `foundation`
 
@@ -129,10 +154,18 @@ standard Dart Sass pipeline (Next.js, Vite, webpack `sass-loader`, or the
 
 ## Theming your brand
 
+> ⚠️ Only relevant if you're on the **Sass pipeline** path above. If you
+> imported the plain `zeus-css/css` build, there is nothing to configure here
+> — remove that import first, then follow the steps below instead. Don't use
+> both.
+
 Every visual token — colors, typography, spacing, radii, shadows, breakpoints
 — lives in **one file**: `zeus.customize.scss`. Copy the keys you want to
 override from `zeus.token.sets.example.scss` (a reference-only file, never
 imported) into your own `zeus.customize.scss` before the `@use` chain resolves.
+Then compile through `@use "zeus-css/foundation"` as shown in
+[Global stylesheet — foundation](#1-global-stylesheet--foundation) — your
+overrides are baked into the CSS your own Sass pipeline emits.
 
 ```scss
 // zeus.customize.scss