zeus-css 1.0.0

package/scss/foundation/core/buttons/variants.scss

@@ -0,0 +1,72 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Variants                                        ║
+// ║                                                               ║
+// ║  Core styles and definitions for variants.                    ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../../../zeus.config" as config;
+
+$_button-variants-defaults: (
+  "primary": (
+    "default": (
+      "background": var(--color-primary),
+      "color": var(--color-text-inverse),
+      "border": none,
+    ),
+    "hover": (
+      "background": var(--color-primary-dark),
+      "color": var(--color-text-inverse),
+      "border": none,
+    ),
+    "active": (
+      "background": var(--color-primary-dark),
+      "color": var(--color-text-inverse),
+      "border": none,
+    ),
+  ),
+  "secondary": (
+    "default": (
+      "background": transparent,
+      "color": var(--color-primary),
+      "border": var(--border-line-sm) solid var(--color-primary),
+    ),
+    "hover": (
+      "color": var(--color-primary-dark),
+      "border-color": var(--color-primary-dark),
+    ),
+    "active": (
+      "color": var(--color-primary-dark),
+      "border-color": var(--color-primary-dark),
+    ),
+  ),
+  "tertiary": (
+    "default": (
+      "background": transparent,
+      "color": var(--color-primary),
+      "border": none,
+    ),
+    "hover": (
+      "color": var(--color-primary-dark),
+    ),
+    "active": (
+      "color": var(--color-primary-dark),
+    ),
+  ),
+  "icon-only": (
+    "default": (
+      "background": transparent,
+      "color": var(--color-primary),
+      "border": none,
+    ),
+    "hover": (
+      "color": var(--color-primary-dark),
+    ),
+    "active": (
+      "color": var(--color-primary-dark),
+    ),
+  ),
+);
+
+// ── Developer Override ──
+$button-variants: map.deep-merge($_button-variants-defaults, config.$zeus-button-variants);

package/scss/foundation/core/design/_design-system.scss

@@ -0,0 +1,41 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Design System                                   ║
+// ║                                                               ║
+// ║  Design tokens and configuration for design system.           ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "./core/basic" as *;
+@use "./colors/base-colors" as *;
+@use "./colors/semantic-colors" as *;
+@use "./typography/typography" as *;
+@use "./dimensions/spaces" as *;
+@use "./dimensions/sizes" as *;
+@use "./layout/grid" as *;
+@use "./borders/border-line" as *;
+@use "./borders/border-radius" as *;
+@use "./effects/shadows" as *;
+@use "./effects/z-index" as *;
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus Design System Master Dictionary                     ║
+// ║  This is the single source of truth for the recursive        ║
+// ║  compiler engine.                                            ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+// NOTE: base $zeus-colors ("color" tokens) are NOT listed here — they are
+// emitted exclusively by semantic-colors.scss's generate-semantic-colors()
+// (called directly from render/root.scss), which also derives the -light/
+// -dark/-muted/-inverse/border/surface variants from them. Including them
+// here too would emit --color-primary (etc.) twice in the compiled output.
+$zeus-design-system: (
+  "base": $base-colors,
+  "size-icon": $icon-size,
+  "space": $space,
+  "border-radius": $border-radius,
+  "border-line": $border-line,
+  "col-gap": $column-gaps,
+  "padding-outer": $outer-padding,
+  "shadow": $shadows,
+  "text": $typography,
+  "z": $z-index,
+);

package/scss/foundation/core/design/_validate.scss

@@ -0,0 +1,114 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Validate                                        ║
+// ║                                                               ║
+// ║  Design tokens and configuration for validate.                ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "sass:meta";
+
+// -----------------------------------------------------------------
+// Validate a simple responsive token: (floor, ceil)
+// Used for: spaces, icon-sizes, border-radius, border-line
+// Clamp by default — no fluid flag needed
+// -----------------------------------------------------------------
+@mixin validate-responsive-token($category, $name, $token-map) {
+  @if not map.has-key($token-map, $name) {
+    @error "[ZEUS Validate] Token '#{$name}' not found in #{$category} map.";
+  }
+
+  $token: map.get($token-map, $name);
+
+  @if meta.type-of($token) != "map" {
+    @error "[ZEUS Validate] #{$category}.#{$name} must be a map, got #{meta.type-of($token)}.";
+  }
+
+  @each $required-key in ("floor", "ceil") {
+    @if not map.has-key($token, $required-key) {
+      @error "[ZEUS Validate] #{$category}.#{$name} is missing required key '#{$required-key}'. Expected format: (floor: N, ceil: N)";
+    }
+  }
+}
+
+// -----------------------------------------------------------------
+// Validate a typography token
+// Expected: (family, size: (floor, ceil), lh, ls, weight)
+// Clamp by default — no fluid flag needed
+// -----------------------------------------------------------------
+@mixin validate-typography-token($name, $token-map) {
+  @if not map.has-key($token-map, $name) {
+    @error "[ZEUS Validate] Typography token '#{$name}' not found.";
+  }
+
+  $token: map.get($token-map, $name);
+
+  @each $required-key in ("family", "size", "lh", "ls", "weight") {
+    @if not map.has-key($token, $required-key) {
+      @error "[ZEUS Validate] typography.#{$name} is missing key '#{$required-key}'. Expected keys: family, size, lh, ls, weight";
+    }
+  }
+
+  // Validate the nested size sub-map
+  $size-map: map.get($token, "size");
+  @if meta.type-of($size-map) != "map" {
+    @error "[ZEUS Validate] typography.#{$name}.size must be a map (floor, ceil), got #{meta.type-of($size-map)}.";
+  }
+
+  @each $size-key in ("floor", "ceil") {
+    @if not map.has-key($size-map, $size-key) {
+      @error "[ZEUS Validate] typography.#{$name}.size is missing '#{$size-key}'. Expected: (floor: N, ceil: N)";
+    }
+  }
+}
+
+// -----------------------------------------------------------------
+// Validate a button size token
+// Expected: (font: (floor, ceil), py: (floor, ceil), px: (floor, ceil))
+// Clamp by default — no fluid flag needed
+// -----------------------------------------------------------------
+@mixin validate-button-size-token($name, $token-map) {
+  @if not map.has-key($token-map, $name) {
+    @error "[ZEUS Validate] Button size '#{$name}' not found.";
+  }
+
+  $token: map.get($token-map, $name);
+
+  @each $prop in ("font", "py", "px") {
+    @if not map.has-key($token, $prop) {
+      @error "[ZEUS Validate] button-sizes.#{$name} is missing '#{$prop}'. Expected keys: font, py, px";
+    }
+
+    $sub: map.get($token, $prop);
+    @if meta.type-of($sub) != "map" {
+      @error "[ZEUS Validate] button-sizes.#{$name}.#{$prop} must be a map, got #{meta.type-of($sub)}.";
+    }
+
+    @each $sub-key in ("floor", "ceil") {
+      @if not map.has-key($sub, $sub-key) {
+        @error "[ZEUS Validate] button-sizes.#{$name}.#{$prop} is missing '#{$sub-key}'. Expected: (floor: N, ceil: N)";
+      }
+    }
+  }
+}
+
+// -----------------------------------------------------------------
+// Batch validate: run on entire maps at once
+// Call these in a debug/dev build to catch all errors early
+// -----------------------------------------------------------------
+@mixin validate-all-responsive($category, $token-map) {
+  @each $name, $_ in $token-map {
+    @include validate-responsive-token($category, $name, $token-map);
+  }
+}
+
+@mixin validate-all-typography($token-map) {
+  @each $name, $_ in $token-map {
+    @include validate-typography-token($name, $token-map);
+  }
+}
+
+@mixin validate-all-button-sizes($token-map) {
+  @each $name, $_ in $token-map {
+    @include validate-button-size-token($name, $token-map);
+  }
+}

package/scss/foundation/core/design/borders/border-line.scss

@@ -0,0 +1,29 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Border Line                                     ║
+// ║                                                               ║
+// ║  Design tokens and configuration for border line.             ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../../../../zeus.config" as config;
+@use "../_validate" as validate;
+
+// ╔══════════════════════════════════════════════════════════╗
+// ║  📐 BORDER WIDTH TOKENS                                 
+// ║                                                         
+// ║  Format: "name": (floor: N, ceil: N)
+// ║  Output CSS variable: --border-line-{name}               
+// ╚══════════════════════════════════════════════════════════╝
+
+// ── Defaults ─────────────────────────────────────────────────
+$_border-line-defaults: (
+  "none": (floor: 0,   ceil: 0),
+  "xs": (floor: 1,   ceil: 2),
+  "sm": (floor: 1.5, ceil: 3),
+  "md": (floor: 2,   ceil: 4),
+  "lg": (floor: 4,   ceil: 8),
+);
+
+// ── Developer can override specific keys ──
+$border-line: map.deep-merge($_border-line-defaults, config.$zeus-border-line);
+@include validate.validate-all-responsive("border-line", $border-line);

package/scss/foundation/core/design/borders/border-radius.scss

@@ -0,0 +1,31 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Border Radius                                   ║
+// ║                                                               ║
+// ║  Design tokens and configuration for border radius.           ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../../../../zeus.config" as config;
+@use "../_validate" as validate;
+
+// ╔══════════════════════════════════════════════════════════╗
+// ║  📐 BORDER RADIUS TOKENS                                
+// ║                                                         
+// ║  Format: "name": (floor: N, ceil: N)
+// ║  Output CSS variable: --border-radius-{name}             
+// ╚══════════════════════════════════════════════════════════╝
+
+// ── Defaults ─────────────────────────────────────────────────
+$_border-radius-defaults: (
+  "none":    (floor: 0,   ceil: 0),
+  "xs":      (floor: 2,   ceil: 4),
+  "sm":      (floor: 8,   ceil: 12),
+  "md":      (floor: 16,  ceil: 24),
+  "lg":      (floor: 20,  ceil: 32),
+  "xl":      (floor: 38,  ceil: 64),
+  "rounded": (floor: 360, ceil: 360),
+);
+
+// ── Developer can override specific keys ──
+$border-radius: map.deep-merge($_border-radius-defaults, config.$zeus-border-radius);
+@include validate.validate-all-responsive("border-radius", $border-radius);

package/scss/foundation/core/design/buttons/sizes.scss

@@ -0,0 +1,32 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Sizes                                           ║
+// ║                                                               ║
+// ║  Design tokens and configuration for sizes.                   ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../../../../zeus.config" as config;
+@use "../_validate" as validate;
+
+// ╔══════════════════════════════════════════════════════════╗
+// ║  📐 BUTTON SIZES                                        
+// ║                                                         
+// ║  Each size defines fluid scaling for:                   
+// ║  - font (Font Size)                                     
+// ║  - py (Padding Y)                                       
+// ║  - px (Padding X)                                       
+// ╚══════════════════════════════════════════════════════════╝
+
+$_button-sizes-defaults: (
+  "2xs": ( font: (floor: 11, ceil: 12), py: (floor: 4, ceil: 6),   px: (floor: 8, ceil: 12) ),
+  "xs":  ( font: (floor: 12, ceil: 13), py: (floor: 6, ceil: 8),   px: (floor: 12, ceil: 16) ),
+  "sm":  ( font: (floor: 13, ceil: 14), py: (floor: 8, ceil: 10),  px: (floor: 16, ceil: 20) ),
+  "md":  ( font: (floor: 14, ceil: 16), py: (floor: 10, ceil: 12), px: (floor: 20, ceil: 24) ),
+  "lg":  ( font: (floor: 16, ceil: 20), py: (floor: 12, ceil: 16), px: (floor: 24, ceil: 32) ),
+  "xl":  ( font: (floor: 18, ceil: 22), py: (floor: 16, ceil: 20), px: (floor: 32, ceil: 40) ),
+  "2xl": ( font: (floor: 20, ceil: 26), py: (floor: 20, ceil: 24), px: (floor: 40, ceil: 48) ),
+);
+
+// ── Developer Override ──
+$button-sizes: map.deep-merge($_button-sizes-defaults, config.$zeus-button-sizes);
+@include validate.validate-all-button-sizes($button-sizes);

package/scss/foundation/core/design/colors/_color-derivation.scss

@@ -0,0 +1,80 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Color Derivation                                ║
+// ║                                                               ║
+// ║  Pure functions for design tokens color derivation.            ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  🎨 Shared Color Derivation Math                              ║
+// ║                                                              ║
+// ║  Single source of truth for how *-light/*-dark/muted/border   ║
+// ║  tokens relate to their base color. Used by BOTH:             ║
+// ║    · semantic-colors.scss  → the default palette              ║
+// ║    · engine/theme-builder.scss → zeus-theme() named themes    ║
+// ║  so a named theme's border/muted "weight" always matches the  ║
+// ║  default palette's, instead of two independently hand-tuned   ║
+// ║  percentages drifting apart.                                  ║
+// ║                                                                ║
+// ║  $base/$fg/$bg accept anything usable inside oklch()/          ║
+// ║  color-mix() — a literal color or a var(--color-*) reference.  ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+// Picks a readable foreground (near-white or near-dark) for text/icons sitting
+// ON TOP of $base, by switching on the base color's own OKLCH lightness.
+//
+// How the switch works, entirely in CSS so it stays reactive: inside
+// oklch(from …) the `l` channel is available to calc(), so
+// `clamp(0, (0.6 - l) * 1000, 1)` collapses to exactly 0 (base is light →
+// use dark text) or 1 (base is dark → use light text). That 0/1 then
+// interpolates between the framework's own text (0.218) and background
+// (0.976) lightness values, at chroma 0 so the result is neutral.
+//
+// Why CSS and not Sass compile-time math: a consumer can reassign
+// --color-primary at runtime (JS, [data-theme]) and every derived token has
+// to follow. Computing this in Sass would freeze it at build time and break
+// that contract — the same reason *-light/*-dark above are CSS-derived.
+//
+// LIMITATION — this is a best-effort improvement, not a WCAG guarantee.
+// OKLCH lightness is not WCAG relative luminance, so a single threshold
+// cannot clear 4.5:1 for every possible input: a highly saturated green or
+// yellow around l≈0.6 has high luminance in both directions and bottoms out
+// near 3.5:1 whichever foreground is chosen. It picks the *better* of the two
+// options for any color, and all six of the framework's own default colors
+// clear AA comfortably (4.55–7.40:1, asserted by scripts/test-compile.mjs
+// check 8). If you override a brand color, re-run that check.
+@function derive-on-color($base) {
+  @return oklch(from #{$base} calc(0.218 + 0.758 * clamp(0, (0.6 - l) * 1000, 1)) 0 h);
+}
+
+@function derive-light($base) {
+  @return oklch(from #{$base} calc(l + 0.15) c h);
+}
+
+@function derive-dark($base) {
+  @return oklch(from #{$base} calc(l - 0.15) c h);
+}
+
+// Derives the default card/surface background elevation from the page background.
+@function derive-surface($background) {
+  @return oklch(from #{$background} calc(l - 0.02) c h);
+}
+
+@function derive-muted($foreground, $background) {
+  @return color-mix(in oklch, #{$foreground}, #{$background} 50%);
+}
+
+@function derive-border($foreground, $background) {
+  @return color-mix(in oklch, #{$foreground}, #{$background} 80%);
+}
+
+@function derive-border-strong($foreground, $background) {
+  @return color-mix(in oklch, #{$foreground}, #{$background} 60%);
+}
+
+@function derive-surface-subtle($surface, $foreground) {
+  @return color-mix(in oklch, #{$surface}, #{$foreground} 5%);
+}
+
+@function derive-warning-subtle($warning, $background) {
+  @return color-mix(in oklch, #{$warning}, #{$background} 75%);
+}

package/scss/foundation/core/design/colors/base-colors.scss

@@ -0,0 +1,31 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Base Colors                                     ║
+// ║                                                               ║
+// ║  Design tokens and configuration for base colors.             ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../../../../zeus.config" as config;
+
+// ╔══════════════════════════════════════════════════════════╗
+// ║  🎨 BASE COLORS (Static)                                
+// ║                                                         
+// ║  These are the system reference colors. Core UI uses    
+// ║  semantic tokens instead of these.                      
+// ╚══════════════════════════════════════════════════════════╝
+
+// ── Defaults ─────────────────────────────────────────────────
+$_base-defaults: (
+  "pure-white": oklch(100% 0 0),
+  "pure-black": oklch(0%   0 0),
+  "pure-gray":  oklch(50%  0 0),
+
+  "system": (
+    "success": oklch(65% 0.20 145),
+    "warning": oklch(72% 0.18 85),
+    "error":   oklch(55% 0.25 25),
+  ),
+);
+
+// ── Developer Override ──
+$base-colors: map.deep-merge($_base-defaults, config.$zeus-base-colors);

package/scss/foundation/core/design/colors/semantic-colors.scss

@@ -0,0 +1,130 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Semantic Colors                                 ║
+// ║                                                               ║
+// ║  Design tokens and configuration for semantic colors.         ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "sass:list";
+@use "../../../../zeus.config" as config;
+@use "./color-derivation" as derive;
+
+// The full set of $zeus-colors keys this file actually reads (via _c()/_has()
+// below). Anything else is a typo or a key nothing consumes — e.g. "surface-
+// subtle"/"warning-subtle" are always derived and can't be overridden despite
+// looking like the rest of this list. _c()'s fallback-on-missing-key design is
+// intentional for the 5 core colors (a typo'd override is indistinguishable
+// from "not set" without this check), so this warns instead of erroring.
+$_known-color-keys: (
+  "primary", "primary-light", "primary-dark",
+  "secondary", "secondary-light", "secondary-dark",
+  "accent", "accent-light", "accent-dark",
+  "text", "text-inverse", "text-muted",
+  "background", "surface",
+  "border", "border-strong"
+);
+@each $_key in map.keys(config.$zeus-colors) {
+  @if not list.index($_known-color-keys, $_key) {
+    @warn "[Zeus Color] '#{$_key}' in $zeus-colors is not a recognized token name and will be ignored. Did you mean one of: #{$_known-color-keys}?";
+  }
+}
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  Zeus Semantic Colors — Direct OKLCH Categories              ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@function _c($key, $fallback) {
+  $val: map.get(config.$zeus-colors, $key);
+  @if $val {
+    @return $val;
+  } @else {
+    @return $fallback;
+  }
+}
+
+// Whether $key is explicitly defined in the developer's $zeus-colors map.
+// Used so derived colors (below) never silently overwrite an explicit value —
+// the pipeline in root-generator.scss already emitted it from the map directly.
+@function _has($key) {
+  @return map.has-key(config.$zeus-colors, $key);
+}
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  Private: emit static set of derived tokens                  ║
+// ║  from 5 resolved base colors.                               ║
+// ║  Single source of truth shared with engine/theme-builder.scss. ║
+// ╚══════════════════════════════════════════════════════════════╝
+@mixin _emit-static-color-vars($primary, $secondary, $accent, $text, $bg) {
+  --color-primary: #{$primary};
+  @if not _has("primary-light") {
+    --color-primary-light: #{derive.derive-light("var(--color-primary)")};
+  }
+  @if not _has("primary-dark") {
+    --color-primary-dark: #{derive.derive-dark("var(--color-primary)")};
+  }
+
+  --color-secondary: #{$secondary};
+  @if not _has("secondary-light") {
+    --color-secondary-light: #{derive.derive-light("var(--color-secondary)")};
+  }
+  @if not _has("secondary-dark") {
+    --color-secondary-dark: #{derive.derive-dark("var(--color-secondary)")};
+  }
+
+  --color-accent: #{$accent};
+  @if not _has("accent-light") {
+    --color-accent-light: #{derive.derive-light("var(--color-accent)")};
+  }
+  @if not _has("accent-dark") {
+    --color-accent-dark: #{derive.derive-dark("var(--color-accent)")};
+  }
+
+  --color-background: #{$bg};
+  @if not _has("surface") {
+    --color-surface: #{derive.derive-surface("var(--color-background)")};
+  }
+
+  --color-text: #{$text};
+  @if not _has("text-inverse") {
+    --color-text-inverse: #{$bg};
+  }
+
+  @if not _has("text-muted") {
+    --color-text-muted: #{derive.derive-muted("var(--color-text)", "var(--color-background)")};
+  }
+  @if not _has("border") {
+    --color-border: #{derive.derive-border("var(--color-text)", "var(--color-background)")};
+  }
+  @if not _has("border-strong") {
+    --color-border-strong: #{derive.derive-border-strong("var(--color-text)", "var(--color-background)")};
+  }
+
+  --color-surface-subtle: #{derive.derive-surface-subtle("var(--color-surface)", "var(--color-text)")};
+  --color-warning-subtle: #{derive.derive-warning-subtle("var(--base-system-warning)", "var(--color-background)")};
+}
+
+// ── CSS Custom Properties ──────────────────────────────────────
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  Semantic Colors Layer                                       ║
+// ║                                                              ║
+// ║  Maps the flat configuration directly to CSS custom variables.║
+// ║  There is no intermediate layer. Colors flow DIRECTLY from   ║
+// ║  zeus.config.scss to CSS variables, ensuring optimal perf.   ║
+// ╚══════════════════════════════════════════════════════════════╝
+@mixin generate-semantic-colors() {
+  // Capture base configurations
+  $primary: _c(primary, oklch(50.0% 0.232 259.6));
+  $secondary: _c(secondary, oklch(74.7% 0.174 60.6));
+  $accent: _c(accent, oklch(52.0% 0.153 164.1));
+  $text: _c(text, oklch(21.8% 0.000 0.0));
+  $bg: _c(background, oklch(97.6% 0.000 0.0));
+
+  :root {
+    color-scheme: light;
+    @include _emit-static-color-vars($primary, $secondary, $accent, $text, $bg);
+  }
+}
+
+// ── Sass variable (for use inside SCSS logic) ──────────────────
+// Exposes the resolved flat map so other SCSS files can loop over it
+$colors: config.$zeus-colors !default;

package/scss/foundation/core/design/core/basic.scss

@@ -0,0 +1,40 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Basic                                           ║
+// ║                                                               ║
+// ║  Design tokens and configuration for basic.                   ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../../../../zeus.config" as config;
+
+// ╔══════════════════════════════════════════════════════════╗
+// ║  ⚙️  ZEUS CORE — Fluid Scaling & Base Tokens
+// ║
+// ║  Defines the viewport boundaries that drive all fluid
+// ║  calculations (clamp-based sizing, typography, spacing).
+// ║  Every token below can be overridden before @use.
+// ╚══════════════════════════════════════════════════════════╝
+
+// ─── Container bounds ───────────────────────────────
+// The container width range: fluid values scale linearly
+// Auto-derive container inner bounds inside the Engine (floor = 375 - 32 = 343, ceil = 1920 - 128 = 1792)
+$_c-floor-calc: map.get(config.$zeus-viewports, "mobile") - (map.get(config.$zeus-viewport-gutter, "mobile") * 2);
+$_c-ceil-calc:  map.get(config.$zeus-viewports, "desktop") - (map.get(config.$zeus-viewport-gutter, "desktop") * 2);
+
+$_container-bounds-base-defaults: (
+  floor: $_c-floor-calc,
+  ceil:  $_c-ceil-calc,
+);
+$_container-bounds-defaults: map.merge($_container-bounds-base-defaults, config.$zeus-container-bounds);
+
+// ── Developer can set $container-bounds BEFORE @use to override ──
+$container-bounds: () !default;
+$container-bounds: map.merge($_container-bounds-defaults, $container-bounds);
+
+// ─── Root typographic unit ───────────────────────────────────
+// Reference size for all rem-based calculations.
+$root-font-size: config.$zeus-root-font-size !default;
+
+// ─── Global focus ring ───────────────────────────────────────
+// Accessible focus indicator applied system-wide.
+$focus-ring: config.$zeus-focus-ring !default;

package/scss/foundation/core/design/dimensions/sizes.scss

@@ -0,0 +1,29 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Sizes                                           ║
+// ║                                                               ║
+// ║  Design tokens and configuration for sizes.                   ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../../../../zeus.config" as config;
+@use "../_validate" as validate;
+
+// ╔══════════════════════════════════════════════════════════╗
+// ║  📐 ICON SIZES — Edit values here                       
+// ║                                                         
+// ║  Format: "name": (floor: N, ceil: N)                    
+// ║  Output CSS variable: --size-icon-{name}                
+// ╚══════════════════════════════════════════════════════════╝
+
+// ── Defaults ─────────────────────────────────────────────────
+$_icon-size-defaults: (
+  "xs":  (floor: 14, ceil: 18),
+  "sm":  (floor: 20, ceil: 24),
+  "md":  (floor: 22, ceil: 32),
+  "lg":  (floor: 38, ceil: 48),
+  "xl":  (floor: 48, ceil: 64),
+);
+
+// ── Developer can set $icon-size BEFORE @use to override specific keys ──
+$icon-size: map.deep-merge($_icon-size-defaults, config.$zeus-icon-size);
+@include validate.validate-all-responsive("icon-size", $icon-size);