zeus-css 1.0.11 → 1.0.13

package/bin/postinstall.js

@@ -1,13 +0,0 @@
-#!/usr/bin/env node
-try {
-  if (process.env.CI) {
-    process.exit(0);
-  }
-  console.log('');
-  console.log('⚡ Zeus CSS installed.');
-  console.log('   Run `npx zeus-css init` to get local zeus.config.scss / zeus.customize.scss files you can edit.');
-  console.log('   (Skip this if you only want the default theme via zeus-css/dist/zeus.css.)');
-  console.log('');
-} catch (e) {
-  // Never fail an install just because the reminder couldn't print.
-}

package/scss/.stylelintrc.json

@@ -1,41 +0,0 @@
-{
-  "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/scss/API.md

@@ -1,175 +0,0 @@
-# Zeus CSS — Public API Surface (v1.0.0)
-
-This document is the semver contract. Everything listed here is **public and
-stable**: it will not change or be removed except in a major version bump
-(`2.0.0`), following [Semantic Versioning](https://semver.org/). Everything
-*not* listed here — including anything explicitly marked "internal" below —
-is free to change in a minor or patch release without notice.
-
-Generated references (`llms.txt`, `cheatsheet.md`, `zeus.tokens.json`) are
-regenerated from source on every `npm run prepack` and always reflect the
-current public surface described here. If they ever disagree with this file,
-this file wins.
-
-## 1. Entry points
-
-| Import | Emits CSS? | Use in |
-|---|---|---|
-| `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 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`)
-
-Every `!default` variable in these two files is public: name, accepted
-values/shape, and default value are all part of the contract.
-
-**Feature toggles** — `$zeus-enable-responsive-classes`, `$zeus-enable-animation-classes`,
-`$zeus-enable-grid-system`, `$zeus-enable-shadow-classes`,
-`$zeus-enable-color-utilities`, `$zeus-enable-property-registration`.
-
-**Naming & compile strategy** — `$zeus-use-prefix`, `$zeus-class-prefix`,
-`$zeus-version`. All responsive utilities are mobile-first (`min-width`);
-there is no desktop-first mode and no config knob for one — see CHANGELOG
-for the removal rationale.
-
-**Fluid engine bounds** — `$zeus-container-bounds`, `$zeus-root-font-size`,
-`$zeus-focus-ring`.
-
-**Layout** — `$zeus-outer-max-width`, `$zeus-breakpoints`, `$zeus-outer-padding`,
-`$zeus-column-gaps`.
-
-**Design tokens** (`zeus.customize.scss`, forwarded through `zeus.config.scss`)
-— `$zeus-colors`, and every other token map documented inline in that file
-(typography, spacing, radii, border widths, icon sizes, shadows, z-index).
-Reference values for every key: `zeus.token.sets.example.scss`.
-
-Any Sass map above may have individual keys overridden without providing the
-whole map — that merge behavior is itself part of the contract.
-
-## 3. Public mixins & functions
-
-Everything forwarded by `foundation/core/design`, `foundation/core/engine`,
-and `foundation/core/api` — i.e. everything reachable via
-`@use "zeus" as *`. The full catalog with signatures lives in
-[`llms.txt`](llms.txt) / [`cheatsheet.md`](cheatsheet.md) (auto-generated, do
-not hand-edit). Highlights: `padding()`, `margin()`, `gap()`, `border-radius()`,
-`border-line()`, `box-size()`, `text()`, `color()`, `zeus-theme()`,
-`apply-shadow()` / `elevation()` / `hover-shadow()` / `card-shadow()` / the
-rest of the shadow mixin family, `screen-above()` / `screen-below()` /
-`screen-between()` / `suppress-on()`, `fade-in()` / `slide-in()` / `scale()` /
-`bounce()` / `pulse()` / `rotate()`, the `btn-*` mixin family, and the `p()` /
-`m()` / `g()` / `r()` / `t()` / `sz()` shorthand aliases.
-
-**Internal, not public** — anything whose name starts with `_` (e.g.
-`_z-control-base`, `_emit-static-color-vars`, `_register-color-tokens`),
-and every function/mixin in `foundation/core/engine/_fluid-core.scss`, whose
-file header explicitly states it is private. `gen-cheatsheet.mjs` already
-excludes these from the generated catalog for the same reason.
-
-## 4. Public utility class families
-
-Every class family listed in [`llms.txt`](llms.txt) / [`cheatsheet.md`](cheatsheet.md)
-under "Utility Class Families" — layout (`flex-*`, `grid-*`, `d-*`), spacing
-(`gap-*`), color (`bg-*`, `color-*`, `border-color-*`), typography (`text-*`),
-shadows (`shadow-*`), borders (`border-radius-*`, `border-line-*`), sizing
-(`w-*`, `h-*`, `min-w-*`, `max-w-*`, `box-*`, `icon-*`), position (`static`,
-`relative`, `absolute`, `fixed`, `sticky`, `inset-*`, `top-*`, `bottom-*`,
-`inset-inline-start-*`, `inset-inline-end-*`), z-index (`layer-*`), animation
-(`animate-*`, `delay-*`, `duration-*`), aspect ratio (`aspect-*`), opacity
-(`opacity-*`), flex-grow/shrink/order, overflow/object-fit, responsive
-visibility (`hidden-*`), the compound utility classes (`surface`,
-`surface-flat`, `section-wrap`, `section-wrap-narrow`, `glass`, `divider`,
-`sr-only`, `truncate`, `line-clamp-*`, `highlight`, `article`), `.container`,
-and the `btn-*` button classes. (Renamed from the `zeus-*` prefix —
-`.z-*` is reserved exclusively for the framework's fixed BEM components —
-card, modal, form controls — which do NOT participate in
-`$zeus-use-prefix`.)
-
-When `$zeus-use-prefix: true`, every class in this list is emitted with
-`$zeus-class-prefix` prepended — the prefixing behavior itself is part of the
-contract, not just the unprefixed names.
-
-## 5. Public components (`foundation/views/components/`)
-
-These class-based components and their documented modifiers:
-
-- **`.z-card`**, `.z-card__media` and the modifiers documented in `_card.scss`
-- **`.z-modal-backdrop`**, `.z-modal`
-- **`.z-field`**, `.z-field--invalid`, `.z-field-group`, `.z-field__helper`,
-  `.z-field__error`, `.z-label`, `.z-label--required`, `.z-input`,
-  `.z-textarea`, `.z-select`, `.z-checkbox`, `.z-radio`
-- **`.z-badge`** — variants `--primary/--secondary/--accent/--success/
-  --warning/--error`, modifier `--solid`, element `.z-badge__dot`
-- **`.z-alert`**, **`.z-avatar`** (+ `.z-avatar-group`), **`.z-table`**,
-  **`.z-breadcrumb`**, **`.z-pagination`** — variants/elements as documented
-  in their respective partials
-- **`.z-tabs`** — `.z-tabs__list`, `.z-tabs__tab`, `.z-tabs__panel`. State is
-  driven by the native `aria-selected` / `hidden` attributes; which tab is
-  selected is the consumer's to manage (Zeus ships no JS).
-- **`.z-tooltip`**, **`.z-dropdown`** (+ `.z-dropdown__list/__item/__divider`,
-  `__item--danger`) — built on the native `popover` attribute and CSS anchor
-  positioning. See README "Browser support": absence of anchor positioning
-  degrades placement only. Hover-triggered tooltips need consumer JS;
-  `popovertarget` alone gives click-to-toggle.
-- **`.z-toast-region`** + **`.z-toast`** (+ `__icon/__body/__title/__message/
-  __close`, variants `--success/--warning/--danger/--info`) — the region is
-  `popover="manual"`; auto-dismiss timing is the consumer's.
-- **`.z-skeleton`** — modifiers `--text/--title/--avatar/--block`
-
-The private `_z-control-base()` mixin these share is an implementation
-detail (§3) — only the class names and their documented states (default,
-hover, `:focus-visible`, `:disabled`, invalid) are guaranteed.
-
-## 6. Public design tokens (CSS custom properties)
-
-Every CSS custom property emitted by `foundation` (the `--color-*`,
-`--space-*`, `--text-*`, `--shadow-*`, `--border-radius-*`, `--border-line-*`,
-`--size-icon-*`, `--z-*`, and responsive `--*` vars declared in
-`zeus.customize.scss`) is public. The canonical, always-current list — name,
-value, and type — is generated straight from the compiled CSS into
-[`zeus.tokens.json`](zeus.tokens.json) (W3C Design Tokens format) by
-`npm run gen:tokens`; nothing in that file is hand-maintained, so it cannot
-drift from what actually ships.
-
-## 7. What is explicitly NOT public
-
-- Anything under `foundation/views/render/` other than the class names listed
-  in §4 — the internal `load-*` mixins, file layout, and forward chain are
-  free to change.
-- `foundation/core/engine/_fluid-core.scss` and any `_`-prefixed
-  mixin/function anywhere in the tree (§3).
-- The internal cascade-layer wiring (`_layer-order.scss`) and the fact that
-  it must forward first — an implementation detail of how layers get their
-  order, not something consumers should depend on directly.
-- `scripts/*.mjs` (token/cheatsheet generators, and the compile-matrix test
-  suite) — tooling, not shipped API.
-- File/folder structure inside `foundation/` beyond the two entry points —
-  files may be split, merged, or moved as long as the public mixins,
-  functions, classes, and tokens above keep working identically.
-
-## 8. Versioning commitment
-
-Starting at `1.0.0`: no breaking change to anything in §1–§6 without a major
-version bump. A breaking change is any of — a public mixin/function being
-renamed, removed, or changing its required arguments; a public class being
-renamed or removed; a public CSS custom property being renamed, removed, or
-changing what it resolves to for the same config; a config variable's name,
-accepted values, or default changing. Adding new mixins, functions, classes,
-tokens, or config keys is a minor release. Bug fixes that don't change the
-above are patch releases.

package/scss/LICENSE

@@ -1,21 +0,0 @@
-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

@@ -1,193 +0,0 @@
-# ⚡ 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
-```
-
-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:
-
-```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`
-
-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
-
-> ⚠️ 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
-$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.
-- `API.md` — the full public API surface: entry points, config variables,
-  mixins/functions, utility classes, components, and design tokens.
-
-## License
-
-MIT © Stavros Kosmas Lazaris