zeus-css 1.0.2 → 1.0.4

package/package.json

@@ -1,13 +1,24 @@
 {
   "name": "zeus-css",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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"
+    "zeus-css": "./bin/init.js"
+  },
+  "scripts": {
+    "postinstall": "node ./bin/postinstall.js"
   },
   "exports": {
     ".": {
@@ -26,27 +37,11 @@
   "files": [
     "scss",
     "dist",
-    "bin",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md",
-    "API.md",
-    "cheatsheet.md",
-    "llms.txt"
+    "bin"
   ],
-  "engines": {
-    "node": ">=16"
-  },
-  "scripts": {
-    "build:css": "sass scss/foundation/foundation.scss dist/zeus.css --style=expanded && sass scss/foundation/foundation.scss dist/zeus.min.css --style=compressed",
-    "prepack": "npm run build:css"
-  },
   "peerDependencies": {
     "sass": "^1.60.0"
   },
-  "devDependencies": {
-    "sass": "^1.99.0"
-  },
   "keywords": [
     "zeus",
     "css",
@@ -57,4 +52,4 @@
     "design-tokens",
     "type-safe"
   ]
-}
+}

package/scss/.stylelintrc.json

@@ -0,0 +1,41 @@
+{
+  "extends": "stylelint-config-standard-scss",
+  "ignoreFiles": ["zeus.token.sets.example.scss"],
+  "rules": {
+    "no-empty-source": null,
+    "scss/at-rule-no-unknown": true,
+
+    "selector-class-pattern": null,
+    "custom-property-pattern": null,
+    "scss/dollar-variable-pattern": null,
+    "scss/at-function-pattern": null,
+
+    "alpha-value-notation": null,
+    "color-function-notation": null,
+    "hue-degree-notation": null,
+    "value-keyword-case": null,
+
+    "no-descending-specificity": null,
+    "declaration-block-single-line-max-declarations": null,
+    "shorthand-property-no-redundant-values": null,
+    "font-family-name-quotes": null,
+    "property-no-vendor-prefix": null,
+
+    "scss/at-mixin-argumentless-call-parentheses": null,
+    "scss/at-mixin-pattern": null,
+    "scss/at-if-closing-brace-newline-after": null,
+    "scss/at-if-closing-brace-space-after": null,
+    "scss/at-if-no-null": null,
+    "scss/at-else-empty-line-before": null,
+    "scss/double-slash-comment-empty-line-before": null,
+    "scss/double-slash-comment-whitespace-inside": null,
+    "scss/dollar-variable-empty-line-before": null,
+    "scss/dollar-variable-colon-space-after": null,
+    "scss/operator-no-unspaced": null,
+    "declaration-empty-line-before": null,
+    "rule-empty-line-before": null,
+    "at-rule-empty-line-before": null,
+    "comment-empty-line-before": null,
+    "scss/comment-no-empty": null
+  }
+}

package/{CHANGELOG.md → scss/CHANGELOG.md}

@@ -6,10 +6,8 @@ documented in [`API.md`](API.md).
 
 ## [Unreleased]
 
-Working toward the `1.0.0` tag — not yet published (no npm release, no git
-tag exists as of this entry). [`API.md`](API.md) documents the intended
-public API surface; semver will become binding once `1.0.0` is actually
-published, not before.
+Published to npm as `zeus-css`. [`API.md`](API.md) documents the public API
+surface this changelog's semver contract is now binding against.
 
 ### Removed (since first written)
 - **Dark mode**, entirely — `$zeus-dark-mode-strategy` and

package/scss/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stavros Kosmas Lazaris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/scss/README.md

@@ -0,0 +1,160 @@
+# ⚡ Zeus CSS
+
+Zeus is a fluid-first SCSS design system. Every size, space, and font size scales
+smoothly between a mobile floor and a desktop ceiling using native CSS
+`clamp()` driven by container-query units (`cqi`) — no breakpoint jumps, no
+`calc()` guesswork. Colors are OKLCH-based semantic tokens with automatic
+light/dark derivation. The whole system is expressed as plain Sass maps, which
+makes it easy for both humans and AI coding assistants to read, extend, and
+reason about.
+
+- **Fluid by default** — `clamp()` scaling for spacing, type, radii, borders, icons.
+- **Semantic OKLCH tokens** — define 5 base colors, get light/dark/muted/border variants derived automatically.
+- **Cascade layers** — `reset → tokens → base → layout → components → utilities`, so utility classes always win without `!important`.
+- **Zero-emission module entry** — `@use "zeus" as *` in a component's `.module.scss` gives you every mixin/function with **no** leaked CSS.
+- **Config-first** — every token lives in one file you can override; nothing is hardcoded past that boundary.
+
+## Browser support
+
+Zeus targets evergreen browsers only — there is no fallback path for the core
+and none is planned. There is no IE11, no legacy Safari, and no polyfill
+story: if you need to support browsers older than ~2023, Zeus is not the
+right choice.
+
+**Required (the whole framework depends on these).** Cascade layers
+(`@layer`), container query units (`cqi`, `container-type`), `@property`,
+relative color syntax (`oklch(from …)`), `:has()`, `color-mix()`. All are
+Baseline "Widely available" in current Chrome/Edge, Firefox, and Safari.
+
+**Progressive enhancement (a few components use these and degrade if
+absent).** These are *not* uniformly Baseline — check current support for
+your targets rather than assuming:
+
+| Feature | Used by | Without it you get |
+| --- | --- | --- |
+| `popover` attribute | `.z-tooltip`, `.z-dropdown`, `.z-toast-region` | No top-layer rendering or light-dismiss — these three need it to function; verify support before relying on them |
+| CSS anchor positioning (`position-anchor`, `position-area`) | `.z-tooltip`, `.z-dropdown` | Still a fully working popover, just placed by the UA default instead of anchored to its trigger |
+| `@starting-style`, `transition-behavior: allow-discrete` | `.z-tooltip`, `.z-dropdown` enter/exit | Instant show/hide instead of a fade — purely cosmetic |
+
+Anchor positioning has the narrowest support of the three (Chromium shipped
+it well ahead of the other engines). The components are written so its
+absence costs placement, never functionality.
+
+## Install
+
+```bash
+npm install zeus-css
+```
+
+## Two entry points
+
+Zeus ships two distinct ways to consume it — pick the right one per file.
+
+### 1. Global stylesheet — `foundation`
+
+Import **once**, at your app root. Emits the full compiled CSS: reset, design
+tokens as CSS custom properties, typography base, and every utility class
+(`.padding-lg`, `.text-h1`, `.grid-cols-3`, …).
+
+```scss
+// app/globals.scss
+@use "zeus-css/foundation";
+```
+
+### 2. Component modules — `zeus`
+
+Import in **every** `.module.scss` component file. Exposes all mixins and
+functions (`@include padding(...)`, `@include text(...)`, `color(...)`, …) but
+emits **zero** CSS of its own — only the rules you actually write.
+
+```scss
+// Button.module.scss
+@use "zeus-css/zeus" as *;
+
+.button {
+  @include padding("md", "x");
+  @include text("button");
+  @include border-radius("sm");
+  background: color("primary");
+  color: var(--color-text-inverse);
+
+  &:hover {
+    background: color("primary-dark");
+  }
+}
+```
+
+## 5-minute quickstart
+
+```scss
+// 1. app/globals.scss — load the framework once
+@use "zeus-css/foundation";
+```
+
+```tsx
+// 2. app/layout.tsx — import the global stylesheet
+import "./globals.scss";
+```
+
+```scss
+// 3. components/Card.module.scss — build a component with the API
+@use "zeus-css/zeus" as *;
+
+.card {
+  @include padding("lg");
+  @include border-radius("md");
+  @include card-shadow();
+  background: var(--color-surface);
+  border: var(--border-line-xs) solid var(--color-border);
+}
+
+.title {
+  @include text("h4");
+  color: var(--color-text);
+}
+```
+
+```tsx
+// components/Card.tsx
+import styles from "./Card.module.scss";
+
+export function Card({ children }: { children: React.ReactNode }) {
+  return <div className={styles.card}>{children}</div>;
+}
+```
+
+That's it — no build config, no PostCSS plugin. Zeus compiles with any
+standard Dart Sass pipeline (Next.js, Vite, webpack `sass-loader`, or the
+`sass` CLI directly).
+
+## Theming your brand
+
+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.
+
+```scss
+// zeus.customize.scss
+$zeus-colors: (
+  "primary": oklch(60% 0.2 250),
+  "primary-light": oklch(75% 0.15 250),
+  "primary-dark": oklch(45% 0.25 250),
+  // ...
+);
+```
+
+Layout/engine behavior (prefixing, responsive strategy, fluid viewport bounds)
+lives in `zeus.config.scss` — separate from design tokens on purpose, so
+brand changes and structural changes never collide in the same diff.
+
+## Learn more
+
+- `zeus.token.sets.example.scss` — full reference of every default token value.
+- `CHANGELOG.md` — what changed between versions.
+- The framework's docs site (component gallery, `/tokens-reference`, full API
+  reference) already exists in this monorepo — see `API.md` §6.
+
+## License
+
+MIT © Stavros Kosmas Lazaris