zeus-css 1.0.6 → 1.0.9

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 +55 -55
  4. package/scss/API.md +3 -4
  5. package/scss/CHANGELOG.md +3 -5
  6. package/scss/README.md +2 -2
  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,55 +1,55 @@
1
- {
2
- "name": "zeus-css",
3
- "version": "1.0.6",
4
- "description": "⚡ A Premium, Zero-Emission, Fluid-Scaling CSS Framework based on Sass SCSS Engine",
5
- "author": "Stavros Lazaris",
6
- "license": "MIT",
7
- "homepage": "https://www.npmjs.com/package/zeus-css",
8
- "repository": {
9
- "type": "git",
10
- "url": "git+https://github.com/zeus-css/zeus-css-framework.git"
11
- },
12
- "bugs": {
13
- "url": "https://github.com/zeus-css/zeus-css-framework/issues"
14
- },
15
- "main": "./dist/zeus.css",
16
- "style": "./dist/zeus.css",
17
- "bin": {
18
- "zeus-css": "./bin/init.js"
19
- },
20
- "scripts": {
21
- "postinstall": "node ./bin/postinstall.js"
22
- },
23
- "exports": {
24
- ".": {
25
- "sass": "./scss/zeus.scss",
26
- "css": "./dist/zeus.css",
27
- "default": "./dist/zeus.css"
28
- },
29
- "./foundation": "./scss/foundation/foundation.scss",
30
- "./zeus": "./scss/zeus.scss",
31
- "./config": "./scss/zeus.config.scss",
32
- "./customize": "./scss/zeus.customize.scss",
33
- "./dist/*": "./dist/*",
34
- "./scss/*": "./scss/*",
35
- "./bin/*": "./bin/*"
36
- },
37
- "files": [
38
- "scss",
39
- "dist",
40
- "bin"
41
- ],
42
- "peerDependencies": {
43
- "sass": "^1.60.0"
44
- },
45
- "keywords": [
46
- "zeus",
47
- "css",
48
- "scss",
49
- "sass",
50
- "framework",
51
- "fluid-design",
52
- "design-tokens",
53
- "type-safe"
54
- ]
55
- }
1
+ {
2
+ "name": "zeus-css",
3
+ "version": "1.0.9",
4
+ "description": "⚡ A Premium, Zero-Emission, Fluid-Scaling CSS Framework based on Sass SCSS Engine",
5
+ "author": "Stavros Lazaris",
6
+ "license": "MIT",
7
+ "homepage": "https://www.npmjs.com/package/zeus-css",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/zeus-css/zeus-css-framework.git"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/zeus-css/zeus-css-framework/issues"
14
+ },
15
+ "main": "./dist/zeus.css",
16
+ "style": "./dist/zeus.css",
17
+ "bin": {
18
+ "zeus-css": "./bin/init.js"
19
+ },
20
+ "scripts": {
21
+ "postinstall": "node ./bin/postinstall.js"
22
+ },
23
+ "exports": {
24
+ ".": {
25
+ "sass": "./scss/zeus.scss",
26
+ "css": "./dist/zeus.css",
27
+ "default": "./dist/zeus.css"
28
+ },
29
+ "./foundation": "./scss/foundation/foundation.scss",
30
+ "./zeus": "./scss/zeus.scss",
31
+ "./config": "./scss/zeus.config.scss",
32
+ "./customize": "./scss/zeus.customize.scss",
33
+ "./dist/*": "./dist/*",
34
+ "./scss/*": "./scss/*",
35
+ "./bin/*": "./bin/*"
36
+ },
37
+ "files": [
38
+ "scss",
39
+ "dist",
40
+ "bin"
41
+ ],
42
+ "peerDependencies": {
43
+ "sass": "^1.60.0"
44
+ },
45
+ "keywords": [
46
+ "zeus",
47
+ "css",
48
+ "scss",
49
+ "sass",
50
+ "framework",
51
+ "fluid-design",
52
+ "design-tokens",
53
+ "type-safe"
54
+ ]
55
+ }
package/scss/API.md CHANGED
@@ -38,7 +38,7 @@ values/shape, and default value are all part of the contract.
38
38
  **Naming & compile strategy** — `$zeus-use-prefix`, `$zeus-class-prefix`,
39
39
  `$zeus-version`. All responsive utilities are mobile-first (`min-width`);
40
40
  there is no desktop-first mode and no config knob for one — see CHANGELOG
41
- for the 26.07 removal rationale.
41
+ for the removal rationale.
42
42
 
43
43
  **Fluid engine bounds** — `$zeus-container-bounds`, `$zeus-root-font-size`,
44
44
  `$zeus-focus-ring`.
@@ -88,7 +88,7 @@ shadows (`shadow-*`), borders (`border-radius-*`, `border-line-*`), sizing
88
88
  visibility (`hidden-*`), the compound utility classes (`surface`,
89
89
  `surface-flat`, `section-wrap`, `section-wrap-narrow`, `glass`, `divider`,
90
90
  `sr-only`, `truncate`, `line-clamp-*`, `highlight`, `article`), `.container`,
91
- and the `btn-*` button classes. (Renamed from the `zeus-*` prefix 25.07 —
91
+ and the `btn-*` button classes. (Renamed from the `zeus-*` prefix —
92
92
  `.z-*` is reserved exclusively for the framework's fixed BEM components —
93
93
  card, modal, form controls — which do NOT participate in
94
94
  `$zeus-use-prefix`.)
@@ -137,8 +137,7 @@ Every CSS custom property emitted by `foundation` (the `--color-*`,
137
137
  value, and type — is generated straight from the compiled CSS into
138
138
  [`zeus.tokens.json`](zeus.tokens.json) (W3C Design Tokens format) by
139
139
  `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.
140
+ drift from what actually ships.
142
141
 
143
142
  ## 7. What is explicitly NOT public
144
143
 
package/scss/CHANGELOG.md CHANGED
@@ -61,8 +61,7 @@ surface this changelog's semver contract is now binding against.
61
61
  - **`zeus.tokens.json`** — every design token (colors, spacing, typography,
62
62
  shadows, radii, borders, icon sizes, z-index, custom vars) in W3C Design
63
63
  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.
64
+ so it cannot drift from what actually ships.
66
65
  - **`llms.txt` / `cheatsheet.md`** — auto-generated catalog of every public
67
66
  mixin, function, and utility class family, via `npm run gen:cheatsheet`.
68
67
  Both regenerate automatically on `npm run prepack`.
@@ -143,9 +142,8 @@ surface this changelog's semver contract is now binding against.
143
142
  exists in this repository. Reworded to reference the compile-matrix test
144
143
  suite that does.
145
144
  - `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.
145
+ future release" while one already existed — corrected to stop disclaiming
146
+ it.
149
147
  - **Package name unified to `zeus-css`.** The source manifest and all docs
150
148
  said `@lazaris/zeus-css` while the published package `scripts/build-package.ts`
151
149
  actually generates is — and always was — unscoped `zeus-css`, which is also
package/scss/README.md CHANGED
@@ -152,8 +152,8 @@ brand changes and structural changes never collide in the same diff.
152
152
 
153
153
  - `zeus.token.sets.example.scss` — full reference of every default token value.
154
154
  - `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.
155
+ - `API.md` — the full public API surface: entry points, config variables,
156
+ mixins/functions, utility classes, components, and design tokens.
157
157
 
158
158
  ## License
159
159
 
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),