zeus-css 1.0.0

package/scss/foundation/core/engine/shadows.scss

@@ -0,0 +1,186 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Shadows                                         ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for shadows.            ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+// CSS-Var-First: references the already-emitted --shadow-{key} :root token
+// instead of inlining the raw shadow value at every call site — same
+// pattern as padding()/border-radius() (layout.scss) and text()
+// (typographics.scss). Keeps the value runtime-overridable (JS,
+// [data-theme]) and keeps the literal value in one place instead of
+// repeated in every component that references it.
+@function _shadow-var($key) {
+  @return var(--shadow-#{$key});
+}
+
+// -----------------------------------------------------------------------------
+// APPLY SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Usage: @include apply-shadow("md");
+@mixin apply-shadow($size: "md") {
+  box-shadow: _shadow-var($size);
+}
+
+// -----------------------------------------------------------------------------
+// ELEVATION MIXIN
+// -----------------------------------------------------------------------------
+// Usage: @include elevation(2); // Applies shadow-md
+@mixin elevation($level: 1) {
+  @if $level == 0 {
+    box-shadow: _shadow-var("none");
+  } @else if $level == 1 {
+    box-shadow: _shadow-var("sm");
+  } @else if $level == 2 {
+    box-shadow: _shadow-var("md");
+  } @else if $level == 3 {
+    box-shadow: _shadow-var("lg");
+  } @else if $level == 4 {
+    box-shadow: _shadow-var("xl");
+  } @else if $level == 5 {
+    box-shadow: _shadow-var("2xl");
+  } @else {
+    @warn "Elevation level #{$level} not found. Using default 'md'.";
+    box-shadow: _shadow-var("md");
+  }
+}
+
+// -----------------------------------------------------------------------------
+// HOVER SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Usage: @include hover-shadow("sm", "lg");
+@mixin hover-shadow($default: "md", $hover: "lg") {
+  box-shadow: _shadow-var($default);
+  transition: box-shadow 0.3s ease;
+
+  &:hover {
+    box-shadow: _shadow-var($hover);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// FOCUS SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Usage: @include focus-shadow("outline");
+@mixin focus-shadow($shadow: "outline") {
+  // :focus-visible (not plain :focus) — outline is only removed when the
+  // shadow is actually shown, so keyboard users never lose focus indication.
+  // The outline itself is kept, just transparent: invisible in normal
+  // rendering (box-shadow is the real affordance), but forced-colors mode
+  // paints outlines with a system color regardless of author color, so
+  // focus stays visible even when box-shadow (stripped under forced-colors)
+  // disappears.
+  &:focus-visible {
+    box-shadow: _shadow-var($shadow);
+    outline: 2px solid transparent;
+    outline-offset: 2px;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// INTERACTIVE SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Combines hover and focus states
+// Usage: @include interactive-shadow("md", "lg", "outline");
+@mixin interactive-shadow($default: "md", $hover: "lg", $focus: "outline") {
+  box-shadow: _shadow-var($default);
+  transition: box-shadow 0.3s ease;
+
+  &:hover {
+    box-shadow: _shadow-var($hover);
+  }
+
+  &:focus-visible {
+    box-shadow: _shadow-var($focus);
+    // See focus-shadow() above: transparent, not none — stays invisible
+    // normally but forced-colors mode paints it with a system color so
+    // focus survives box-shadow being stripped.
+    outline: 2px solid transparent;
+    outline-offset: 2px;
+  }
+
+  &:active {
+    box-shadow: _shadow-var($default);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// CARD SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Pre-configured for cards with hover effect
+// Usage: @include card-shadow();
+@mixin card-shadow() {
+  box-shadow: _shadow-var("card");
+  transition: box-shadow 0.3s ease;
+
+  &:hover {
+    box-shadow: _shadow-var("card-hover");
+  }
+}
+
+// -----------------------------------------------------------------------------
+// SEMANTIC SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Usage: @include semantic-shadow("primary");
+@mixin semantic-shadow($type: "primary") {
+  box-shadow: _shadow-var($type);
+}
+
+// -----------------------------------------------------------------------------
+// GLOW EFFECT MIXIN
+// -----------------------------------------------------------------------------
+// Usage: @include glow-effect("primary", 0.5);
+@mixin glow-effect($color: rgba(59, 130, 246, 0.5), $blur: 20px) {
+  box-shadow: 0 0 $blur 0 $color;
+}
+
+// -----------------------------------------------------------------------------
+// INNER SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Usage: @include inner-shadow();
+@mixin inner-shadow($size: "inner") {
+  box-shadow: _shadow-var($size);
+}
+
+// -----------------------------------------------------------------------------
+// LAYERED SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Combines multiple shadows
+// Usage: @include layered-shadow("md", "primary");
+@mixin layered-shadow($shadow1, $shadow2) {
+  box-shadow: _shadow-var($shadow1), _shadow-var($shadow2);
+}
+
+// -----------------------------------------------------------------------------
+// CONDITIONAL SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Applies shadow only on certain states
+// Usage: @include conditional-shadow("hover", "lg");
+@mixin conditional-shadow($state: "hover", $shadow: "md") {
+  @if $state == "hover" {
+    &:hover {
+      box-shadow: _shadow-var($shadow);
+      transition: box-shadow 0.3s ease;
+    }
+  } @else if $state == "focus" {
+    &:focus-visible {
+      box-shadow: _shadow-var($shadow);
+      // See focus-shadow() above: transparent, not none — forced-colors
+      // mode paints it with a system color regardless of the author value.
+      outline: 2px solid transparent;
+      outline-offset: 2px;
+    }
+  } @else if $state == "active" {
+    &:active {
+      box-shadow: _shadow-var($shadow);
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+// REMOVE SHADOW MIXIN
+// -----------------------------------------------------------------------------
+// Usage: @include no-shadow();
+@mixin no-shadow() {
+  box-shadow: none !important;
+}

package/scss/foundation/core/engine/shortcuts.scss

@@ -0,0 +1,30 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Shortcuts                                       ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for shortcuts.          ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "./layout" as *;
+@use "./typographics" as *;
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus Shortcuts — Write less, do more                    ║
+// ║                                                              ║
+// ║  Full-name mixins remain available. These are opt-in aliases ║
+// ║  for rapid prototyping.                                      ║
+// ║                                                              ║
+// ║  p("lg")         → padding: var(--space-lg)                  ║
+// ║  p("lg", "x")    → padding-inline: var(--space-lg)           ║
+// ║  m("xl", "top")  → margin-top: var(--space-xl)               ║
+// ║  t("h3")         → font: 600 clamp(...) / 1.25 Manrope      ║
+// ║  r("md")         → border-radius: var(--border-radius-md)    ║
+// ║  sz("lg")        → width/height: var(--size-icon-lg)         ║
+// ║  g("md")         → gap: var(--space-md)                      ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@mixin p($size, $dir: null) { @include padding($size, $dir); }
+@mixin m($size, $dir: null) { @include margin($size, $dir); }
+@mixin g($size, $dir: null) { @include gap($size, $dir); }
+@mixin r($type)             { @include border-radius($type); }
+@mixin t($type)             { @include text($type); }
+@mixin sz($type)            { @include box-size($type); }

package/scss/foundation/core/engine/sizing.scss

@@ -0,0 +1,49 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Sizing                                          ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for sizing.             ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:math";
+@use "sass:map";
+@use "./fluid-core" as fc;
+@use "../design/core/basic" as *;
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  📐 Zeus Sizing Engine — Clamp by Default                    ║
+// ║                                                              ║
+// ║  Generates CSS clamp() for any (min, max, container) pair.   ║
+// ║  Applies responsive fluid scaling to gaps, outer margins,     ║
+// ║                                                              ║
+// ║  Output units: px  (layout values, not typography)           ║
+// ║  Always fluid — no flag needed. If min == max → static.     ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+// ── Public API ───────────────────────────────────────────────────
+//
+// useclamp-sizing($min, $max, $c-floor?, $c-ceil?, $precision?)
+//
+// Parameters
+//   $min        — smallest value in px (unitless number), at $c-floor
+//   $max        — largest value in px (unitless number), at $c-ceil
+//   $c-floor    — container width where scaling starts (default: 320)
+//   $c-ceil     — container width where scaling ends   (default: 2560)
+//   $precision  — decimal places in compiled CSS      (default: 3)
+//
+// Returns: clamp() string in px. Static #{$min}px only if min == max.
+//
+// Usage:
+//   padding: useclamp-sizing(12, 24);
+//   gap:     useclamp-sizing(8, 16, 320, 1440);
+//
+@function useclamp-sizing($min,
+  $max,
+  $c-floor: map.get($container-bounds, "floor"),
+  $c-ceil: map.get($container-bounds, "ceil"),
+  $precision: 1) {
+  @if $min ==$max {
+    @return #{$min}px;
+  }
+
+  @return fc.zeus-cqi-fluid($min, $max, $c-floor, $c-ceil, "px", $precision);
+}

package/scss/foundation/core/engine/theme-builder.scss

@@ -0,0 +1,83 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Theme Builder                                   ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for theme builder.      ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "../design/colors/color-derivation" as derive;
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  🎨 Zeus Theme Builder                                       ║
+// ║                                                              ║
+// ║  Create a complete theme in one mixin call.                  ║
+// ║  Auto-derives the full default-palette token set (including   ║
+// ║  --color-surface-subtle / --color-warning-subtle, so `code`   ║
+// ║  and `mark` render correctly under the theme too) from just   ║
+// ║  4 required + 1 optional input color.                        ║
+// ║                                                              ║
+// ║  Usage:                                                      ║
+// ║  @include zeus-theme("ocean", (                              ║
+// ║    primary: #0077b6,                                         ║
+// ║    secondary: #00b4d8,                                       ║
+// ║    accent: #ff9f1c,   // optional                             ║
+// ║    body: #caf0f8,                                            ║
+// ║    text: #023e8a,                                            ║
+// ║  ));                                                         ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@mixin zeus-theme($name, $config) {
+  $primary: map.get($config, "primary");
+  $secondary: map.get($config, "secondary");
+  $accent: map.get($config, "accent");
+  $body: map.get($config, "body");
+  $text: map.get($config, "text");
+
+  [data-theme="#{$name}"] {
+    // Layer colors using the same derivation math as the default palette
+    // (core/design/colors/_color-derivation.scss) — so a named theme's
+    // light/dark/muted/border "weight" always matches the default's,
+    // instead of two independently hand-tuned percentages drifting apart.
+    @if $primary {
+      --color-primary: #{$primary};
+      --color-primary-light: #{derive.derive-light("var(--color-primary)")};
+      --color-primary-dark: #{derive.derive-dark("var(--color-primary)")};
+    }
+    @if $secondary {
+      --color-secondary: #{$secondary};
+      --color-secondary-light: #{derive.derive-light("var(--color-secondary)")};
+      --color-secondary-dark: #{derive.derive-dark("var(--color-secondary)")};
+    }
+    @if $accent {
+      --color-accent: #{$accent};
+      --color-accent-light: #{derive.derive-light("var(--color-accent)")};
+      --color-accent-dark: #{derive.derive-dark("var(--color-accent)")};
+    }
+    @if $body {
+      --color-background: #{$body};
+      --color-surface: #{derive.derive-surface("var(--color-background)")};
+    }
+
+    // Font colors — auto-derive from text + body
+    @if $text and $body {
+      --color-text: #{$text};
+      --color-text-muted: #{derive.derive-muted("var(--color-text)", "var(--color-background)")};
+      --color-text-inverse: #{$body};
+    }
+
+    // Border colors — auto-derive from text + body
+    @if $text and $body {
+      --color-border-strong: #{derive.derive-border-strong("var(--color-text)", "var(--color-background)")};
+      --color-border: #{derive.derive-border("var(--color-text)", "var(--color-background)")};
+    }
+
+    // Subtle surfaces — same tokens :where(code)/:where(mark) rely on in the
+    // default palette (render/typography.scss). --base-system-warning is a
+    // global token (core/design/colors/base-colors.scss), shared across all
+    // themes, not redefined per-theme.
+    @if $text and $body {
+      --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)")};
+    }
+  }
+}

package/scss/foundation/core/engine/typographics.scss

@@ -0,0 +1,44 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Typographics                                    ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for typographics.       ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "./helpers" as *;
+@use "./sizing" as *;
+@use "./typography-calc" as *;
+@use "./responsive" as *;
+@use "../design/typography/typography" as *;
+
+// CSS-Var-First typography mixin — v2.1
+// References the :root --text-{type} var instead of recomputing inline.
+// The var is already generated by root-generator.scss.
+@mixin text($type) {
+  @if not map.has-key($typography, $type) {
+    @error "Font type '#{$type}' not found in $typography map";
+  }
+
+  // CSS-Var-First: single reference, computation lives once in :root
+  font: var(--text-#{$type});
+
+  $config: map.get($typography, $type);
+
+  // Letter-spacing — not part of font shorthand, output separately
+  // Fixed: em (proportional to font-size), was incorrectly px in v2.0
+  $letter-spacing: map.get($config, "ls");
+  @if $letter-spacing and $letter-spacing != 0 {
+    letter-spacing: #{$letter-spacing}em;
+  }
+
+  // Role-based auto CSS properties
+  $role: map.get($config, "role");
+  @if $role == "heading" {
+    text-wrap: balance;
+  } @else if $role == "body" {
+    text-wrap: pretty;
+  } @else if $role == "code" {
+    font-variant-ligatures: none;
+    tab-size: 4;
+  }
+}

package/scss/foundation/core/engine/typography-calc.scss

@@ -0,0 +1,71 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Typography Calc                                 ║
+// ║                                                               ║
+// ║  Framework internal engine and mixins for typography calc.    ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "sass:map";
+@use "sass:math";
+@use "../design/core/basic" as *;
+@use "../design/typography/typography" as *;
+@use "./fluid-core" as fc;
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  🔤 Zeus Fluid Typography Engine                             ║
+// ║                                                              ║
+// ║  Generates CSS clamp() for fluid type scaling (CQI).         ║
+// ║  Container bounds sourced from $container-bounds             ║
+// ║  (design/core/basic.scss) — single source of truth.         ║
+// ║                                                              ║
+// ║  Output units: rem  (typography scales with user font prefs) ║
+// ║  Used by: root-generator.scss → --text-{type}           ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+// ── Private: px → rem ────────────────────────────────────────────
+// Converts a unitless px value to rem using $root-font-size (basic.scss).
+// Robust if $root-font-size is ever changed from 16px.
+@function _px-to-rem($px, $precision: 2) {
+  $base: math.div($root-font-size, 1px);
+  @return fc.round-to(math.div($px, $base), $precision);
+}
+
+// ── Public API ───────────────────────────────────────────────────
+//
+// useclamp-typography($typeface, $precision?)
+//
+// Parameters
+//   $typeface   — key in the $typography token map (e.g. "h1", "body-sm")
+//   $precision  — decimal places in compiled CSS (default: 1)
+//
+// Returns: clamp() string in rem units (using cqi).
+//
+//
+@function useclamp-typography($typeface, $precision: 1) {
+  @if not map.has-key($typography, $typeface) {
+    @error "[Zeus] Typography variant '#{$typeface}' not found in $typography map.";
+  }
+
+  $token: map.get($typography, $typeface);
+
+  @if not map.has-key($token, "size") {
+    @error "[Zeus] Typography token '#{$typeface}' is missing a 'size' key.";
+  }
+
+  $size: map.get($token, "size");
+  $min-px: map.get($size, "floor");
+  $max-px: map.get($size, "ceil");
+
+  @if $min-px ==$max-px {
+    @return #{_px-to-rem($min-px, $precision)}rem;
+  }
+
+  // Convert px tokens to rem, then pass to the shared linear engine
+  $min-rem: _px-to-rem($min-px, 2);
+  $max-rem: _px-to-rem($max-px, 2);
+
+  // Convert container bounds to rem so they match the fluid unit scale
+  $c-floor: _px-to-rem(map.get($container-bounds, "floor"), 2);
+  $c-ceil:  _px-to-rem(map.get($container-bounds, "ceil"), 2);
+
+  @return fc.zeus-cqi-fluid($min-rem, $max-rem, $c-floor, $c-ceil, "rem", 1);
+}

package/scss/foundation/foundation.scss

@@ -0,0 +1,29 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Foundation                                      ║
+// ║                                                               ║
+// ║  Core styles and definitions for foundation.                  ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Main Stylesheet                                ║
+// ║                                                              ║
+// ║  Full compiled CSS for production.                           ║
+// ║  Import in root layout or link in HTML.                      ║
+// ║                                                              ║
+// ║  Unlike zeus.scss (which exports only utilities for          ║
+// ║  .module.scss), this file outputs real CSS classes.           ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "../zeus.config" as config;
+@use "./core/design";
+@use "./core/engine";
+@use "./core/api";
+@use "./views/render";
+@use "./views/components";
+@use "./views/patterns";
+
+// The cascade layer order (reset, tokens, base, layout, components,
+// utilities) is established in views/render/_layer-order.scss, forwarded
+// FIRST from views/_render.scss — see that file for why.
+
+/* Zeus CSS v#{config.$zeus-version} */

package/scss/foundation/views/_render.scss

@@ -0,0 +1,13 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Render                                          ║
+// ║                                                               ║
+// ║  Core styles and definitions for render.                      ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@forward "./render/layer-order";
+@forward "./render/reset";
+@forward "./render/property-registration";
+@forward "./render/typography";
+@forward "./render/root";
+@forward "./render/html-body";
+@forward "./render/classes";

package/scss/foundation/views/components/_alert.scss

@@ -0,0 +1,103 @@
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  ⚡ Zeus CSS — Alert                                           ║
+// ║                                                               ║
+// ║  Core structural and visual styles for the alert component.   ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@use "../../core/engine" as *;
+@use "../../core/design" as *;
+
+// ╔══════════════════════════════════════════════════════════════╗
+// ║  🔔 Alert Component                                          ║
+// ║                                                              ║
+// ║  Inline status message with a left accent border and tinted  ║
+// ║  background. Same color-mix() contrast strategy as .z-badge  ║
+// ║  — text is always darkened toward black, independent of the  ║
+// ║  base hue's own lightness.                                   ║
+// ║                                                              ║
+// ║  Usage:                                                      ║
+// ║  <div class="z-alert z-alert--success" role="alert">          ║
+// ║    <p class="z-alert__title">Saved</p>                       ║
+// ║    <p class="z-alert__text">Your changes are live.</p>       ║
+// ║    <button class="z-alert__close" aria-label="Dismiss">×</button>║
+// ║  </div>                                                      ║
+// ╚══════════════════════════════════════════════════════════════╝
+
+@layer components {
+  // Mixed toward `transparent`, not `--color-surface` — see .z-badge's
+  // _badge-variant comment for why (surface's defined-but-zero hue
+  // corrupts the circular hue interpolation, verified live).
+  @mixin _alert-variant($css-var) {
+    background: color-mix(in oklch, var(#{$css-var}) 10%, transparent);
+    border-inline-start-color: var(#{$css-var});
+
+    // Same 55%-toward-black ratio as .z-badge — verified to clear 7.3:1
+    // even for the lightest brand hue (accent).
+    .z-alert__title {
+      color: color-mix(in oklch, var(#{$css-var}) 55%, black);
+    }
+  }
+
+  .z-alert {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--space-sm);
+    @include padding("md");
+    @include border-radius("sm");
+    border: var(--border-line-xs) solid var(--color-border);
+    border-inline-start: var(--border-line-md) solid var(--color-border-strong);
+    background: var(--color-surface-subtle);
+
+    &--info     { @include _alert-variant(--color-primary); }
+    &--success  { @include _alert-variant(--base-system-success); }
+    &--warning  { @include _alert-variant(--base-system-warning); }
+    &--error    { @include _alert-variant(--base-system-error); }
+
+    &__icon {
+      flex-shrink: 0;
+      @include box-size(md);
+    }
+
+    &__content {
+      flex: 1 1 auto;
+      min-width: 0;
+    }
+
+    &__title {
+      @include text("body-sm-bold");
+      color: var(--color-text);
+      margin: 0;
+    }
+
+    &__text {
+      @include text("body-sm");
+      color: var(--color-text-muted);
+      margin: 0;
+
+      .z-alert__title + & {
+        margin-top: var(--space-3xs);
+      }
+    }
+
+    &__close {
+      appearance: none;
+      border: none;
+      background: transparent;
+      flex-shrink: 0;
+      @include text("body");
+      color: var(--color-text-muted);
+      cursor: pointer;
+      padding: 0;
+      line-height: 1;
+
+      &:hover {
+        color: var(--color-text);
+      }
+
+      &:focus-visible {
+        outline: $focus-ring;
+        outline-offset: 2px;
+      }
+    }
+  }
+}