zeus-css 1.0.6 → 1.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/README.md +21 -1
  2. package/bin/init.js +31 -0
  3. package/package.json +1 -1
  4. package/scss/API.md +16 -9
  5. package/scss/CHANGELOG.md +13 -5
  6. package/scss/README.md +37 -4
  7. package/scss/foundation/core/design/layout/grid.scss +3 -3
  8. package/scss/foundation/core/engine/shortcuts.scss +1 -1
  9. package/scss/foundation/core/engine/sizing.scss +3 -3
  10. package/scss/foundation/core/engine/typographics.scss +3 -3
  11. package/scss/foundation/views/components/_badge.scss +1 -1
  12. package/scss/foundation/views/components/_card.scss +1 -1
  13. package/scss/foundation/views/render/classes/_compounds.scss +1 -1
  14. package/scss/foundation/views/render/classes/_sections.scss +1 -1
  15. package/scss/foundation/views/render/classes/_utilities.scss +1 -1
  16. package/scss/foundation/views/render/classes/grid.scss +2 -2
  17. package/scss/scripts/gen-tokens.mjs +4 -5
  18. package/scss/scripts/test-compile.mjs +18 -20
  19. package/scss/zeus.config.scss +4 -1
  20. package/scss/zeus.customize.scss +4 -2
package/README.md CHANGED
@@ -19,6 +19,23 @@ import 'zeus-css/dist/zeus.css';
19
19
 
20
20
  > `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.
21
21
 
22
+ **Where that import goes, per setup:**
23
+
24
+ | Setup | Entry file | Import |
25
+ | --- | --- | --- |
26
+ | Next.js (App Router) | `app/layout.tsx` | `import 'zeus-css/dist/zeus.css';` |
27
+ | Next.js (Pages Router) | `pages/_app.tsx` | `import 'zeus-css/dist/zeus.css';` |
28
+ | React + Vite | `src/main.tsx` | `import 'zeus-css/dist/zeus.css';` |
29
+ | Create React App | `src/index.tsx` | `import 'zeus-css/dist/zeus.css';` |
30
+ | Vue 3 + Vite | `src/main.ts` | `import 'zeus-css/dist/zeus.css';` |
31
+ | Nuxt 3 | `nuxt.config.ts` | `css: ['zeus-css/dist/zeus.css']` |
32
+ | Astro | shared `Layout.astro` | `import 'zeus-css/dist/zeus.css';` in the frontmatter |
33
+ | Plain HTML, no bundler | `<head>` | `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zeus-css/dist/zeus.css">` or copy the file into your own static folder |
34
+
35
+ Always import it from a single **shared/root** entry point, never from an individual component — Next.js in particular will error on global CSS imported outside the root layout/`_app`.
36
+
37
+ **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.
38
+
22
39
  ### 2. Customize it
23
40
  Run the init command in the folder you want the config files in (you'll see a reminder for this after `npm install` too):
24
41
 
@@ -26,7 +43,7 @@ Run the init command in the folder you want the config files in (you'll see a re
26
43
  npx zeus-css init
27
44
  ```
28
45
 
29
- This drops four files into that folder — not buried in `node_modules`:
46
+ This drops these files into that folder — not buried in `node_modules`:
30
47
 
31
48
  | File | Purpose |
32
49
  | --- | --- |
@@ -34,6 +51,9 @@ This drops four files into that folder — not buried in `node_modules`:
34
51
  | `zeus.customize.scss` | **Edit this.** Design tokens — colors, typography, spacing, shadows. |
35
52
  | `zeus.scss` | Generated bridge. Import it in `.module.scss` files for tokens/mixins. Emits no CSS. |
36
53
  | `zeus.theme.scss` | Generated entry point. Compile it to get your themed global stylesheet. |
54
+ | `zeus-css-env.d.ts` | TypeScript projects only (detected via `tsconfig.json`). Ambient `declare module` so the imports above type-check. |
55
+
56
+ Only `zeus.config.scss` and `zeus.customize.scss` are meant to be hand-edited. Every file above is created only if it's missing — re-running `npx zeus-css init` later (e.g. after upgrading the package) fills in whichever ones you don't have yet, and never touches ones that already exist.
37
57
 
38
58
  Edit your colors in `zeus.customize.scss` using OKLCH:
39
59
 
package/bin/init.js CHANGED
@@ -7,6 +7,13 @@ const configTargetPath = path.join(projectRoot, 'zeus.config.scss');
7
7
  const customizeTargetPath = path.join(projectRoot, 'zeus.customize.scss');
8
8
  const bridgeTargetPath = path.join(projectRoot, 'zeus.scss');
9
9
  const themeTargetPath = path.join(projectRoot, 'zeus.theme.scss');
10
+ const typesTargetPath = path.join(projectRoot, 'zeus-css-env.d.ts');
11
+
12
+ // TypeScript is detected, not assumed — a tsconfig.json in the folder you
13
+ // ran `init` from means TS needs to resolve the .css/.scss imports below.
14
+ // Plain JS projects never see type errors from these imports, so nothing
15
+ // is written for them.
16
+ const isTypeScriptProject = fs.existsSync(path.join(projectRoot, 'tsconfig.json'));
10
17
 
11
18
  const configSource = path.join(__dirname, '..', 'scss', 'zeus.config.scss');
12
19
  const customizeSource = path.join(__dirname, '..', 'scss', 'zeus.customize.scss');
@@ -135,6 +142,30 @@ try {
135
142
  'zeus.theme.scss'
136
143
  );
137
144
 
145
+ // 4. TypeScript only: ambient module declarations so `import 'zeus-css/dist/zeus.css'`
146
+ // (or the local .scss files above) type-check. Most framework scaffolds
147
+ // (Next.js, Vite, Nuxt) already declare `*.css`/`*.scss` globally via their
148
+ // own env.d.ts — this is a harmless no-op there, and a real fix in a bare
149
+ // TS setup that has none. JS projects never need this, so nothing is written.
150
+ if (isTypeScriptProject) {
151
+ const typesContent = `// Auto-generated by \`zeus-css init\`.
152
+ // Lets TypeScript resolve CSS/SCSS side-effect imports from zeus-css
153
+ // (e.g. \`import 'zeus-css/dist/zeus.css'\`, \`import './zeus.theme.scss'\`).
154
+ // Most framework scaffolds (Next.js, Vite, Nuxt) already declare these
155
+ // globally, so this file is often a harmless no-op — safe to delete if so.
156
+ declare module '*.css';
157
+ declare module '*.scss';
158
+ `;
159
+
160
+ writeIfMissing(
161
+ typesTargetPath,
162
+ () => fs.writeFileSync(typesTargetPath, typesContent, 'utf8'),
163
+ 'zeus-css-env.d.ts'
164
+ );
165
+ } else {
166
+ console.log('ℹ️ No tsconfig.json found — skipping zeus-css-env.d.ts (JavaScript project, not needed).');
167
+ }
168
+
138
169
  console.log('\n🚀 Zeus CSS is fully ejected and ready!');
139
170
  console.log('Next steps:');
140
171
  console.log('1. For component .module.scss files, use the bridge (no CSS emitted):');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "zeus-css",
3
- "version": "1.0.6",
3
+ "version": "1.0.10",
4
4
  "description": "⚡ A Premium, Zero-Emission, Fluid-Scaling CSS Framework based on Sass SCSS Engine",
5
5
  "author": "Stavros Lazaris",
6
6
  "license": "MIT",
package/scss/API.md CHANGED
@@ -15,16 +15,24 @@ this file wins.
15
15
 
16
16
  | Import | Emits CSS? | Use in |
17
17
  |---|---|---|
18
- | `@use "zeus-css/foundation";` | Yes — full compiled framework | App root, once |
18
+ | `import "zeus-css/css";` | Yes — precompiled, default tokens only, not customizable | App root, no Sass pipeline |
19
+ | `import "zeus-css/min";` | Yes — same as above, minified | App root, no Sass pipeline, production |
20
+ | `@use "zeus-css/foundation";` | Yes — full compiled framework | App root, once, Sass pipeline |
19
21
  | `@use "zeus-css/zeus" as *;` | No — mixins/functions only | Every `.module.scss` |
20
22
  | `@use "zeus-css/config";` | No | Only if you need raw access to `$zeus-*` config variables |
21
23
  | `@use "zeus-css/customize";` | No | Only if you need raw access to `$zeus-colors` etc. without the rest of config |
22
24
 
25
+ `zeus-css/css` and `zeus-css/min` are static builds of `foundation.scss` with
26
+ default tokens baked in at publish time (`npm run build:css`) — they cannot
27
+ reflect `zeus.customize.scss` overrides. Use one of the two SCSS entry points
28
+ below instead if you need custom tokens.
29
+
23
30
  `package.json` → `files` is the authoritative list of what ships: the
24
- `foundation/**/*.scss` tree, the four entry files above, `zeus.tokens.json`,
25
- `llms.txt`, `cheatsheet.md`, `LICENSE`, `README.md`, `CHANGELOG.md`. Anything
26
- under `foundation/` not reachable through one of the two entry points (see
27
- §6) is an implementation detail even though the file ships.
31
+ `foundation/**/*.scss` tree, the six entry points above (plus their compiled
32
+ `dist/` output), `zeus.tokens.json`, `llms.txt`, `cheatsheet.md`, `LICENSE`,
33
+ `README.md`, `CHANGELOG.md`. Anything under `foundation/` not reachable
34
+ through `foundation` or `zeus` (see §6) is an implementation detail even
35
+ though the file ships.
28
36
 
29
37
  ## 2. Config variables (`zeus.config.scss`, `zeus.customize.scss`)
30
38
 
@@ -38,7 +46,7 @@ values/shape, and default value are all part of the contract.
38
46
  **Naming & compile strategy** — `$zeus-use-prefix`, `$zeus-class-prefix`,
39
47
  `$zeus-version`. All responsive utilities are mobile-first (`min-width`);
40
48
  there is no desktop-first mode and no config knob for one — see CHANGELOG
41
- for the 26.07 removal rationale.
49
+ for the removal rationale.
42
50
 
43
51
  **Fluid engine bounds** — `$zeus-container-bounds`, `$zeus-root-font-size`,
44
52
  `$zeus-focus-ring`.
@@ -88,7 +96,7 @@ shadows (`shadow-*`), borders (`border-radius-*`, `border-line-*`), sizing
88
96
  visibility (`hidden-*`), the compound utility classes (`surface`,
89
97
  `surface-flat`, `section-wrap`, `section-wrap-narrow`, `glass`, `divider`,
90
98
  `sr-only`, `truncate`, `line-clamp-*`, `highlight`, `article`), `.container`,
91
- and the `btn-*` button classes. (Renamed from the `zeus-*` prefix 25.07 —
99
+ and the `btn-*` button classes. (Renamed from the `zeus-*` prefix —
92
100
  `.z-*` is reserved exclusively for the framework's fixed BEM components —
93
101
  card, modal, form controls — which do NOT participate in
94
102
  `$zeus-use-prefix`.)
@@ -137,8 +145,7 @@ Every CSS custom property emitted by `foundation` (the `--color-*`,
137
145
  value, and type — is generated straight from the compiled CSS into
138
146
  [`zeus.tokens.json`](zeus.tokens.json) (W3C Design Tokens format) by
139
147
  `npm run gen:tokens`; nothing in that file is hand-maintained, so it cannot
140
- drift from what actually ships. The live, human-browsable view of the same
141
- data is the app's `/tokens-reference` page.
148
+ drift from what actually ships.
142
149
 
143
150
  ## 7. What is explicitly NOT public
144
151
 
package/scss/CHANGELOG.md CHANGED
@@ -6,6 +6,8 @@ documented in [`API.md`](API.md).
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [1.0.10] — 2026-08-05
10
+
9
11
  Published to npm as `zeus-css`. [`API.md`](API.md) documents the public API
10
12
  surface this changelog's semver contract is now binding against.
11
13
 
@@ -61,8 +63,7 @@ surface this changelog's semver contract is now binding against.
61
63
  - **`zeus.tokens.json`** — every design token (colors, spacing, typography,
62
64
  shadows, radii, borders, icon sizes, z-index, custom vars) in W3C Design
63
65
  Tokens format, generated straight from compiled CSS by `npm run gen:tokens`
64
- so it cannot drift from what actually ships. Consumed live by the app's
65
- `/tokens-reference` page.
66
+ so it cannot drift from what actually ships.
66
67
  - **`llms.txt` / `cheatsheet.md`** — auto-generated catalog of every public
67
68
  mixin, function, and utility class family, via `npm run gen:cheatsheet`.
68
69
  Both regenerate automatically on `npm run prepack`.
@@ -143,9 +144,8 @@ surface this changelog's semver contract is now binding against.
143
144
  exists in this repository. Reworded to reference the compile-matrix test
144
145
  suite that does.
145
146
  - `README.md`'s "Learn more" section said a docs site was "planned for a
146
- future release" while one already exists in this monorepo (the same app
147
- `API.md` §6 points to for `/tokens-reference`) — corrected to point at it
148
- instead of disclaiming it.
147
+ future release" while one already existed — corrected to stop disclaiming
148
+ it.
149
149
  - **Package name unified to `zeus-css`.** The source manifest and all docs
150
150
  said `@lazaris/zeus-css` while the published package `scripts/build-package.ts`
151
151
  actually generates is — and always was — unscoped `zeus-css`, which is also
@@ -159,6 +159,14 @@ surface this changelog's semver contract is now binding against.
159
159
  `.`, `./config`, and the raw `./scss/*` passthrough — so three of the four
160
160
  documented specifiers failed to resolve against the published package.
161
161
  Explicit aliases for all four are now emitted.
162
+ - **`zeus-css/css` and `zeus-css/min` were real, shipped exports
163
+ (`package.json` → `exports`) with no entry in README or `API.md` §1** — a
164
+ dev with no Sass pipeline had no documented way to just import the
165
+ precompiled CSS, and the two specifiers carried no semver contract despite
166
+ already being public. README now leads with them for the no-build-step
167
+ path; `API.md` §1 lists both, with a note that they're static builds of
168
+ `foundation.scss` with default tokens baked in and cannot reflect
169
+ `zeus.customize.scss` overrides.
162
170
  - `$zeus-outer-padding` was declared twice in `zeus.config.scss` — an older
163
171
  `(mobile, desktop)`-shaped default (used internally to auto-derive
164
172
  `$container-bounds`) and a newer `(floor, ceil)`-shaped default (the public
package/scss/README.md CHANGED
@@ -46,9 +46,34 @@ absence costs placement, never functionality.
46
46
  npm install zeus-css
47
47
  ```
48
48
 
49
- ## Two entry points
49
+ No Sass pipeline and no customization needed? Import the precompiled CSS
50
+ once, at your app root, and skip everything below about entry points and
51
+ theming:
50
52
 
51
- Zeus ships two distinct ways to consume it — pick the right one per file.
53
+ ```tsx
54
+ // app/layout.tsx
55
+ import "zeus-css/css"; // or "zeus-css/dist/zeus.css" / "zeus-css/min" for the minified build
56
+ ```
57
+
58
+ ## Two ways to consume Zeus — pick one
59
+
60
+ These are **mutually exclusive** at the app-root level. Never load both in
61
+ the same project.
62
+
63
+ | | No Sass pipeline | Sass pipeline (Next.js, Vite, webpack `sass-loader`) |
64
+ |---|---|---|
65
+ | **Import** | `zeus-css/css` (plain compiled CSS) | `@use "zeus-css/foundation"` |
66
+ | **Customizable?** | No — ships the default token values baked in | Yes — edit `zeus.customize.scss` first (see [Theming your brand](#theming-your-brand)) |
67
+ | **Use when** | You just want the framework as-is, no build step | You want your own brand colors/type/spacing |
68
+
69
+ If you don't need custom theming, skip straight to
70
+ [Install](#install) and use the plain CSS import. If you *do* need custom
71
+ theming, use the SCSS entry point — the precompiled CSS can't reflect your
72
+ overrides, since it was built once, at publish time, with the default tokens.
73
+
74
+ ## Two entry points (SCSS pipeline)
75
+
76
+ Once you're on the SCSS path, Zeus exposes two distinct entry points — pick the right one per file.
52
77
 
53
78
  ### 1. Global stylesheet — `foundation`
54
79
 
@@ -129,10 +154,18 @@ standard Dart Sass pipeline (Next.js, Vite, webpack `sass-loader`, or the
129
154
 
130
155
  ## Theming your brand
131
156
 
157
+ > ⚠️ Only relevant if you're on the **Sass pipeline** path above. If you
158
+ > imported the plain `zeus-css/css` build, there is nothing to configure here
159
+ > — remove that import first, then follow the steps below instead. Don't use
160
+ > both.
161
+
132
162
  Every visual token — colors, typography, spacing, radii, shadows, breakpoints
133
163
  — lives in **one file**: `zeus.customize.scss`. Copy the keys you want to
134
164
  override from `zeus.token.sets.example.scss` (a reference-only file, never
135
165
  imported) into your own `zeus.customize.scss` before the `@use` chain resolves.
166
+ Then compile through `@use "zeus-css/foundation"` as shown in
167
+ [Global stylesheet — foundation](#1-global-stylesheet--foundation) — your
168
+ overrides are baked into the CSS your own Sass pipeline emits.
136
169
 
137
170
  ```scss
138
171
  // zeus.customize.scss
@@ -152,8 +185,8 @@ brand changes and structural changes never collide in the same diff.
152
185
 
153
186
  - `zeus.token.sets.example.scss` — full reference of every default token value.
154
187
  - `CHANGELOG.md` — what changed between versions.
155
- - The framework's docs site (component gallery, `/tokens-reference`, full API
156
- reference) already exists in this monorepo — see `API.md` §6.
188
+ - `API.md` — the full public API surface: entry points, config variables,
189
+ mixins/functions, utility classes, components, and design tokens.
157
190
 
158
191
  ## License
159
192
 
package/scss/foundation/core/design/layout/grid.scss CHANGED
@@ -74,9 +74,9 @@ $column-gaps: map.deep-merge($_column-gaps-defaults, $column-gaps);
74
74
  // floor = mobile minimum, ceil = wide desktop maximum
75
75
 
76
76
  // Based on useclamp-sizing() which defaults to the $container-bounds range
77
- // (320px–2560px, see core/design/core/basic.scss).
78
- // floor: 16 -> 16px padding at the 320px container floor (small mobile)
79
- // ceil: 128 -> 128px padding at the 2560px container ceiling (ultra-wide desktop)
77
+ // (343px–1792px unless overridden, see core/design/core/basic.scss).
78
+ // floor: 16 -> 16px padding at the container floor (small mobile)
79
+ // ceil: 128 -> 128px padding at the container ceiling (ultra-wide desktop)
80
80
  $_outer-padding-base-defaults: (
81
81
  floor: 16,
82
82
  ceil: 64,
package/scss/foundation/core/engine/shortcuts.scss CHANGED
@@ -16,7 +16,7 @@
16
16
  // ║ p("lg") → padding: var(--space-lg) ║
17
17
  // ║ p("lg", "x") → padding-inline: var(--space-lg) ║
18
18
  // ║ m("xl", "top") → margin-top: var(--space-xl) ║
19
- // ║ t("h3") → font: 600 clamp(...) / 1.25 Manrope ║
19
+ // ║ t("h3") → font: 600 clamp(...) / 1.25 Inter ║
20
20
  // ║ r("md") → border-radius: var(--border-radius-md) ║
21
21
  // ║ sz("lg") → width/height: var(--size-icon-lg) ║
22
22
  // ║ g("md") → gap: var(--space-md) ║
package/scss/foundation/core/engine/sizing.scss CHANGED
@@ -26,9 +26,9 @@
26
26
  // Parameters
27
27
  // $min — smallest value in px (unitless number), at $c-floor
28
28
  // $max — largest value in px (unitless number), at $c-ceil
29
- // $c-floor — container width where scaling starts (default: 320)
30
- // $c-ceil — container width where scaling ends (default: 2560)
31
- // $precision — decimal places in compiled CSS (default: 3)
29
+ // $c-floor — container width where scaling starts (default: derived from $container-bounds, 343 unless overridden)
30
+ // $c-ceil — container width where scaling ends (default: derived from $container-bounds, 1792 unless overridden)
31
+ // $precision — decimal places in compiled CSS (default: 1)
32
32
  //
33
33
  // Returns: clamp() string in px. Static #{$min}px only if min == max.
34
34
  //
package/scss/foundation/core/engine/typographics.scss CHANGED
@@ -11,7 +11,7 @@
11
11
  @use "./responsive" as *;
12
12
  @use "../design/typography/typography" as *;
13
13
 
14
- // CSS-Var-First typography mixin — v2.1
14
+ // CSS-Var-First typography mixin.
15
15
  // References the :root --text-{type} var instead of recomputing inline.
16
16
  // The var is already generated by root-generator.scss.
17
17
  @mixin text($type) {
@@ -24,8 +24,8 @@
24
24
 
25
25
  $config: map.get($typography, $type);
26
26
 
27
- // Letter-spacing — not part of font shorthand, output separately
28
- // Fixed: em (proportional to font-size), was incorrectly px in v2.0
27
+ // Letter-spacing — not part of font shorthand, output separately.
28
+ // Unit is em (proportional to font-size), not px.
29
29
  $letter-spacing: map.get($config, "ls");
30
30
  @if $letter-spacing and $letter-spacing != 0 {
31
31
  letter-spacing: #{$letter-spacing}em;
package/scss/foundation/views/components/_badge.scss CHANGED
@@ -15,7 +15,7 @@
15
15
  // ║ of how light the base hue is, so every variant clears WCAG ║
16
16
  // ║ AA on its own tinted background without hand-picking a ║
17
17
  // ║ passing shade per color (the trap that caught .btn-primary ║
18
- // ║ originally — see the audit report P1-3). ║
18
+ // ║ originally). ║
19
19
  // ║ ║
20
20
  // ║ Usage: ║
21
21
  // ║ <span class="z-badge z-badge--success">Active</span> ║
package/scss/foundation/views/components/_card.scss CHANGED
@@ -24,7 +24,7 @@
24
24
  // ║ </article> ║
25
25
  // ╚══════════════════════════════════════════════════════════════╝
26
26
  // NOTE: .surface (views/render/classes/_compounds.scss, renamed from
27
- // .zeus-card 25.07) is a separate, intentional single-class utility card for
27
+ // .zeus-card) is a separate, intentional single-class utility card for
28
28
  // quick composition with other utility classes — not a duplicate of this
29
29
  // BEM component. See its own header.
30
30
 
package/scss/foundation/views/render/classes/_compounds.scss CHANGED
@@ -13,7 +13,7 @@
13
13
  // (padding-*, shadow-*, bg-*, …) on the same element; .z-card is a full BEM
14
14
  // component with dedicated __media/__body/__title/__footer sub-elements for
15
15
  // structured card layouts. Reach for .surface for a quick styled box, .z-card
16
- // when you need the structured markup. (Renamed from .zeus-card 25.07 — see
16
+ // when you need the structured markup. (Renamed from .zeus-card — see
17
17
  // naming-convention decision: .z-* is reserved for the framework's fixed
18
18
  // BEM components, everything else ships bare and is prefixable via
19
19
  // $zeus-use-prefix. Named .surface, not .box, because .box-{size} already
package/scss/foundation/views/render/classes/_sections.scss CHANGED
@@ -12,7 +12,7 @@
12
12
  $spacing-sizes: map.keys(spacing-tokens.$space);
13
13
 
14
14
  // .section-0 (from the "0" key below) already covers the zero-padding
15
- // case — no separate .section-none needed. (Removed 26.07, P2-20: the two
15
+ // case — no separate .section-none needed. (Removed: the two
16
16
  // were an exact duplicate, .section-none hardcoded literal 0 instead of
17
17
  // going through --space-0 like every other size in this family.)
18
18
  @each $size in $spacing-sizes {
package/scss/foundation/views/render/classes/_utilities.scss CHANGED
@@ -32,7 +32,7 @@
32
32
  }
33
33
 
34
34
  // Was ":where(.zeus-article), :where(.article)" — a redundant synonym pair
35
- // for the same selector. Renamed 25.07: .article is now the single name.
35
+ // for the same selector. .article is now the single name.
36
36
  :where(.#{$prefix}article) {
37
37
  > p:last-child {
38
38
  margin-bottom: 0;
package/scss/foundation/views/render/classes/grid.scss CHANGED
@@ -8,8 +8,8 @@
8
8
  // ========================================================================================
9
9
  // Zeus Grid System is based on classes that apply to parent divs, so they affect all children.
10
10
  // This is different from other classes that apply to individual elements (e.g. typography, borders, spacing, etc).
11
- // This approach is different from bootstrap and similar frameworks, but it allows for more flexibility and easier maintenance.
12
- // Bootstrap's approach is to apply classes to individual elements, which can lead to a lot of repetitive code and harder maintenance.
11
+ // Applying classes to the parent instead of each child avoids repetitive per-element classes and
12
+ // keeps layout changes centralized: change one class on the parent div to change the layout of every child.
13
13
  // In Zeus, we apply classes to parent divs, which allows us to change the layout of multiple elements by changing a single class on the parent div.
14
14
  // This also allows for easier responsive design, as we can change the layout of multiple elements by
15
15
  // changing a single class on the parent div for different screen sizes.
package/scss/scripts/gen-tokens.mjs CHANGED
@@ -25,16 +25,15 @@ const { css } = sass.compile(join(ROOT, "foundation/foundation.scss"), {
25
25
  });
26
26
 
27
27
  // ── 2. Extract every custom property declaration ─────────────────
28
- // Matches " --name: value;" lines anywhere in the compiled CSS —
29
- // deliberately not limited to a single :root block, since color-scheme
30
- // strategies ("class"/"attribute") can emit more than one root selector.
28
+ // Matches " --name: value;" lines anywhere in the compiled CSS — not
29
+ // anchored to the :root selector specifically, so this keeps working
30
+ // unchanged if a future token ever needs to be scoped elsewhere.
31
31
  // The value class excludes { and } so this can never accidentally match
32
32
  // INTO a BEM modifier selector like ".z-card--flat:hover { ... }" — without
33
33
  // that exclusion, "--flat:hover {\n box-shadow: none" looks exactly like a
34
34
  // "--flat: <value>;" custom property declaration to a naive regex.
35
35
  const propRegex = /--([a-zA-Z][a-zA-Z0-9-]*):\s*([^;{}]+);/g;
36
- const tokens = new Map(); // name -> value (first occurrence wins — the
37
- // light/base value, consistent across strategies)
36
+ const tokens = new Map(); // name -> value (first occurrence wins)
38
37
  let match;
39
38
  while ((match = propRegex.exec(css)) !== null) {
40
39
  const [, name, value] = match;
package/scss/scripts/test-compile.mjs CHANGED
@@ -169,12 +169,11 @@ try {
169
169
  }
170
170
 
171
171
  // ── 5. Public API smoke test — every public mixin/function ───────
172
- // P2-19: check 2 only ever exercised 3 hand-picked mixins. A mixin that's
173
- // public but never called by the framework's own default build (e.g.
174
- // btn-icon-only() before P0-3) can carry a broken internal @use and nobody
175
- // notices until a consumer reaches for it directly. This calls every public
176
- // mixin/function (same "no leading _" convention as gen-cheatsheet.mjs) at
177
- // least once through the zero-emission entry point.
172
+ // A mixin that's public but never called by the framework's own default
173
+ // build (e.g. btn-icon-only() once did) can carry a broken internal @use
174
+ // and nobody notices until a consumer reaches for it directly. This calls
175
+ // every public mixin/function (same "no leading _" convention as
176
+ // gen-cheatsheet.mjs) at least once through the zero-emission entry point.
178
177
  try {
179
178
  const source = `
180
179
  @use "zeus" as *;
@@ -223,11 +222,10 @@ try {
223
222
  }
224
223
 
225
224
  // ── 6. Config variable usage analysis ─────────────────────────────
226
- // P2-19 "ανάλυση μεταβλητών": every $zeus-* variable declared in
227
- // zeus.config.scss/zeus.customize.scss should actually be read somewhere in
228
- // the engine — an orphaned variable is exactly the shape of the old
229
- // $zeus-breakpoint-strategy (Q5): public config surface for a feature that
230
- // doesn't do anything.
225
+ // Every $zeus-* variable declared in zeus.config.scss/zeus.customize.scss
226
+ // should actually be read somewhere in the engine — an orphaned variable is
227
+ // exactly the shape of the old $zeus-breakpoint-strategy: public config
228
+ // surface for a feature that doesn't do anything.
231
229
  try {
232
230
  const configSrc = readFileSync(join(ROOT, "zeus.config.scss"), "utf8");
233
231
  const customizeSrc = readFileSync(join(ROOT, "zeus.customize.scss"), "utf8");
@@ -267,13 +265,13 @@ try {
267
265
  }
268
266
 
269
267
  // ── 7. CLI bridge template variable integrity ─────────────────────
270
- // The exact bug class from Q5's bonus finding: npx zeus-css init generates a
271
- // bridge file (scripts/build-package.ts's cliContent template, two levels up
272
- // from this package) that forwards named $zeus-* variables into
273
- // @use "zeus-css/scss/zeus.scss" with (...) — a renamed/removed variable on
274
- // either side breaks that bridge silently until someone actually runs init.
275
- // Soft-skips (doesn't fail) if the monorepo-only generator isn't present,
276
- // e.g. when this package is checked out/published standalone.
268
+ // npx zeus-css init generates a bridge file (scripts/build-package.ts's
269
+ // cliContent template, two levels up from this package) that forwards named
270
+ // $zeus-* variables into @use "zeus-css/scss/zeus.scss" with (...) — a
271
+ // renamed/removed variable on either side breaks that bridge silently until
272
+ // someone actually runs init.
273
+ // Soft-skips (doesn't fail) if that generator isn't present in this
274
+ // checkout, e.g. when this package is checked out/published standalone.
277
275
  try {
278
276
  const buildPackagePath = join(ROOT, "..", "..", "scripts", "build-package.ts");
279
277
  if (!existsSync(buildPackagePath)) {
@@ -311,8 +309,8 @@ try {
311
309
  }
312
310
 
313
311
  // ── 8. WCAG AA contrast regression guard ──────────────────────────
314
- // P2-19 "contrast check": the exact class of bug that shipped twice this
315
- // project (P1-3's .btn-primary, then secondary/accent) — a color token gets
312
+ // The exact class of bug that shipped twice in this framework's history
313
+ // (.btn-primary, then secondary/accent) — a color token gets
316
314
  // darkened/lightened without re-checking contrast. Reads the *compiled*
317
315
  // default palette from check 1's output (not a hand-copied literal) so this
318
316
  // can never itself drift from zeus.customize.scss, and fails the build the
package/scss/zeus.config.scss CHANGED
@@ -37,6 +37,9 @@ $zeus-use-prefix: false !default;
37
37
  $zeus-class-prefix: "z-" !default; // Used only if $zeus-use-prefix is true
38
38
  $zeus-version: "1.0.0" !default;
39
39
 
40
+ // ────────────────────────────────────────────────────────────────
41
+ // 3. FLUID ENGINE BOUNDS
42
+ // ────────────────────────────────────────────────────────────────
40
43
  // Viewport limits & outer margins (Design Artboard references)
41
44
  // Internal-only: the gutter between the viewport edge and the container,
42
45
  // at each reference width — used solely to auto-derive $container-bounds
@@ -83,7 +86,7 @@ $zeus-breakpoints: (
83
86
 
84
87
  // Container outer padding — fluid margins (floor→ceil px, unit-less)
85
88
  // Public: drives the compiled --padding-outer CSS var (see
86
- // core/design/layout/grid.scss). Distinct from $zeus-artboard-padding above.
89
+ // core/design/layout/grid.scss). Distinct from $zeus-viewport-gutter above.
87
90
  $zeus-outer-padding: (
88
91
  floor: 16,
89
92
  ceil: 128,
package/scss/zeus.customize.scss CHANGED
@@ -22,6 +22,8 @@
22
22
  // variants, muted, inverse, surface, border, border-strong) is derived
23
23
  // automatically at compile/paint time from these 5. Uncomment any key to
24
24
  // pin an exact value instead of the auto-derived one; the deriver skips
25
+ // any key you've already defined.
26
+ //
25
27
  // You can specify colors using ANY valid CSS format: OKLCH, HEX (#2563eb),
26
28
  // RGB, HSL, or named colors. Zeus converts them dynamically via relative CSS syntax.
27
29
  $zeus-colors: (
@@ -168,7 +170,7 @@ $zeus-z-index: () !default;
168
170
  // ) !default;
169
171
 
170
172
  // ────────────────────────────────────────────────────────────────
171
- // 10. CUSTOM RESPONSIVE VARIABLES
173
+ // 11. CUSTOM RESPONSIVE VARIABLES
172
174
  // ────────────────────────────────────────────────────────────────
173
175
  // Define your own custom CSS variables that change value based on breakpoints.
174
176
  // The variables will be automatically generated inside the :root with media queries.
@@ -198,7 +200,7 @@ $zeus-custom-vars: (
198
200
  ) !default;
199
201
 
200
202
  // ────────────────────────────────────────────────────────────────
201
- // 11. BUTTON VARIANTS
203
+ // 12. BUTTON VARIANTS
202
204
  // ────────────────────────────────────────────────────────────────
203
205
  $zeus-button-variants: (
204
206
  "primary": ("default": ("background": var(--color-primary),