zeus-css 1.0.0

package/scss/CHANGELOG.md

@@ -0,0 +1,281 @@
+# Changelog
+
+All notable changes to Zeus CSS are documented here. This project follows
+[Semantic Versioning](https://semver.org/) against the public API surface
+documented in [`API.md`](API.md).
+
+## [Unreleased]
+
+Working toward the `1.0.0` tag — not yet published (no npm release, no git
+tag exists as of this entry). [`API.md`](API.md) documents the intended
+public API surface; semver will become binding once `1.0.0` is actually
+published, not before.
+
+### Removed (since first written)
+- **Dark mode**, entirely — `$zeus-dark-mode-strategy` and
+  `$zeus-enable-auto-dark-mode` (both mentioned as "Added" just below when
+  this entry was still labeled `1.0.0`) no longer exist. Architecture
+  decision: the framework ships one fixed, WCAG-passing light palette;
+  `semantic-colors.scss` emits a single `:root` block, no strategy branching.
+- `$zeus-breakpoint-strategy` and its `"desktop-first"` reserved value —
+  removed rather than implemented; only mobile-first ever existed as a real
+  strategy, so the config knob offered no real choice. See `API.md`.
+- The `.zeus-*` utility class prefix — renamed to bare class names
+  (`.surface`, `.glass`, `.sr-only`, etc.); `.z-*` is now reserved
+  exclusively for the framework's fixed BEM components (card, modal, form
+  controls) and does not participate in `$zeus-use-prefix`.
+
+### Added
+- **Component library, 3 → 14 components.** Phase 1: `.z-badge`, `.z-alert`,
+  `.z-avatar` (+ `.z-avatar-group`), `.z-table`, `.z-breadcrumb`,
+  `.z-pagination`. Phase 2: `.z-tabs`, `.z-tooltip`, `.z-dropdown`,
+  `.z-toast-region`/`.z-toast`, `.z-skeleton` — the floating ones built on the
+  native `popover` attribute plus CSS anchor positioning (same
+  "let the platform do it" approach as `.z-modal`'s `<dialog>`), with
+  `prefers-reduced-motion` guards and graceful degradation when anchor
+  positioning is unavailable. All are listed in [`API.md`](API.md) §5 and
+  therefore covered by the semver contract.
+- **`derive-on-color()`** (`design/colors/_color-derivation.scss`) — derives a
+  readable foreground for text sitting on any brand color by switching on that
+  color's OKLCH lightness, entirely in CSS so it keeps following runtime
+  overrides. Fixes `.z-badge--solid`, which previously hardcoded white text
+  and so shipped 2.20:1 on the default secondary, 2.34:1 on warning and
+  2.79:1 on success. All six solid variants now clear WCAG AA
+  (4.55–7.40:1, browser-verified). Documented non-guarantee: a single
+  lightness threshold cannot clear AA for *every* possible input color.
+- **CI hardening** (`scripts/test-compile.mjs`, 4 → 8 checks) — public-API
+  smoke test that invokes every public mixin/function, config-variable usage
+  analysis (catches orphaned config surface), CLI-bridge template integrity,
+  and a WCAG AA contrast regression guard over all 10 shipped color pairings.
+- **Form components** (`_form.scss`): `.z-field`, `.z-label`, `.z-input`,
+  `.z-textarea`, `.z-select`, `.z-checkbox`, `.z-radio`, `.z-field-group`, with
+  hover/`:focus-visible`/`:disabled`/invalid states, native `accent-color`
+  theming for checkboxes/radios, and a CSS-only select chevron.
+- **Z-index scale** — `$zeus-z-index` config map, `--z-*` custom properties,
+  and `.layer-{name}` utility classes; `.z-modal`/`.z-modal-backdrop` now use
+  the scale instead of hardcoded `z-index: 999/1000`.
+- New utility class families: sizing (`w-*`, `h-*`, `min-w-*`, `max-w-*`,
+  fraction widths), position (`static`/`relative`/`absolute`/`fixed`/`sticky`,
+  `inset-*`, `top-*`/`bottom-*`, logical `inset-inline-start/end-*`), misc
+  (`opacity-*` in steps of 5, `overflow-*`, `object-*`, `flex-grow/shrink-*`,
+  `order-*`), and `hover:`/`focus:` state variants for every `bg-*`/`color-*`/
+  `border-color-*` class.
+- **`zeus.tokens.json`** — every design token (colors, spacing, typography,
+  shadows, radii, borders, icon sizes, z-index, custom vars) in W3C Design
+  Tokens format, generated straight from compiled CSS by `npm run gen:tokens`
+  so it cannot drift from what actually ships. Consumed live by the app's
+  `/tokens-reference` page.
+- **`llms.txt` / `cheatsheet.md`** — auto-generated catalog of every public
+  mixin, function, and utility class family, via `npm run gen:cheatsheet`.
+  Both regenerate automatically on `npm run prepack`.
+- **`scripts/test-compile.mjs`** — a 4-check compile matrix (default build,
+  module zero-emission, prefix build, config-override contract) using the
+  Sass JS API, run via `npm run test:compile`.
+- **`.stylelintrc.json`** + `npm run lint:scss`, tuned to this codebase's
+  established conventions rather than generic defaults.
+- A GitHub Actions workflow (`zeus-css-ci.yml`) running the compile matrix and
+  lint on every push/PR touching `zeus-css/**`.
+- Shared color-derivation functions (`_color-derivation.scss`:
+  `derive-light`, `derive-dark`, `derive-surface`, `derive-muted`,
+  `derive-border`, `derive-border-strong`, `derive-surface-subtle`,
+  `derive-warning-subtle`) used by both `semantic-colors.scss` and
+  `theme-builder.scss`, closing the gap where `zeus-theme()` previously
+  produced incomplete token sets compared to the default palette.
+- `API.md` — the documented public API surface required for a `1.0.0` tag.
+
+### Changed
+- Shadow presets (`primary`, `secondary`, `glow`, `glow-lg`, `outline`) now
+  derive from `var(--color-primary)` via `oklch(from ... l c h / N)` instead
+  of a hardcoded blue `rgba()`, so they follow custom brand colors.
+- `col-start-*`/`col-end-*` grid utilities generated via `@for` loop instead
+  of hand-written rules.
+
+### Fixed
+- **`engine/shadows.scss`'s mixins didn't follow the codebase's own
+  CSS-Var-First pattern.** `padding()`/`border-radius()`/`text()` all
+  reference the already-emitted `:root` custom property (`var(--space-md)`,
+  etc.) instead of recomputing the value — documented as a deliberate
+  pattern in `layout.scss`/`typographics.scss`, for two reasons: the value
+  stays runtime-overridable (JS, `[data-theme]`), and the literal value
+  lives once instead of being repeated at every call site. Every shadow
+  mixin (`apply-shadow()`, `elevation()`, `hover-shadow()`, `focus-shadow()`,
+  `interactive-shadow()`, `card-shadow()`, `semantic-shadow()`,
+  `inner-shadow()`, `layered-shadow()`, `conditional-shadow()`) instead
+  called a Sass function (`shadow($key)`) that inlined the raw
+  `box-shadow` value at compile time — e.g. `.z-card` had a literal
+  `box-shadow: 0px 2px 8px 0px rgba(...), ...;` sitting right next to a
+  correctly-referenced `border-radius: var(--border-radius-md);`. A
+  component styled with `card-shadow()` would not pick up a runtime change
+  to `--shadow-card`, unlike every other token-driven mixin in the
+  framework. Added a private `_shadow-var($key)` helper
+  (`var(--shadow-#{$key})`) and switched all 16 call sites to it — same
+  compiled visual result under default config, now consistent with the
+  rest of the engine, and the repeated literal value is gone from the
+  compiled output (each shadow's value now appears once, at `:root`,
+  instead of once per component using it).
+- **Focus indicators could disappear entirely under Windows High Contrast
+  Mode (`forced-colors`), a WCAG 2.4.7 Focus Visible risk.** Five call sites
+  removed the native focus outline (`outline: none`) and relied solely on
+  `box-shadow`/`border-color` to show `:focus-visible` —
+  `_form.scss`'s `_z-control-base()`, the `focus-shadow()`,
+  `interactive-shadow()`, and `conditional-shadow()` mixins in
+  `engine/shadows.scss`, and the `.focus:shadow-outline`/`.focus:shadow-primary`
+  utility classes. `forced-colors` mode strips `box-shadow` entirely, so
+  keyboard focus had no visible indicator left in that mode. Changed
+  `outline: none` to `outline: 2px solid transparent` at each site: fully
+  invisible in normal rendering (box-shadow remains the visible affordance),
+  but browsers paint outlines with a system color under `forced-colors`
+  regardless of the author-specified color, so focus stays visible exactly
+  when it's needed. `button-base-reset()` and the link reset in
+  `typography.scss` already used the correct pattern (`outline: revert` /
+  a real `outline` on `:focus-visible`) and needed no change.
+- `btn-size()` emitted physical `padding-left`/`padding-right` for its
+  horizontal padding while every other spacing mixin in the framework already
+  uses logical properties — the one RTL leak in an otherwise RTL-clean
+  codebase. Now `padding-inline` (and, for consistency, `padding-block`
+  instead of `padding-top`/`padding-bottom`).
+- `_tooltip.scss`'s anchor-positioning fallback comment claimed an
+  `@supports` guard "protects the whole feature" — no such block exists
+  anywhere in the codebase. The actual mechanism (browsers ignore the
+  unrecognized `position-anchor`/`position-area` values and fall back to
+  default top-layer placement) needed no guard; the comment now says so.
+- `API.md` referenced `foundation/core/design/_fluid-core.scss` twice (§3,
+  §7) — the file has always lived in `foundation/core/engine/`.
+- `API.md` §7 listed "the CI workflow" among excluded tooling; no CI workflow
+  exists in this repository. Reworded to reference the compile-matrix test
+  suite that does.
+- `README.md`'s "Learn more" section said a docs site was "planned for a
+  future release" while one already exists in this monorepo (the same app
+  `API.md` §6 points to for `/tokens-reference`) — corrected to point at it
+  instead of disclaiming it.
+- **Package name unified to `zeus-css`.** The source manifest and all docs
+  said `@lazaris/zeus-css` while the published package `scripts/build-package.ts`
+  actually generates is — and always was — unscoped `zeus-css`, which is also
+  what the `zeus-css init` bridge imports (`@use "zeus-css/scss/zeus.scss"`).
+  Following the README's `npm install @lazaris/zeus-css` therefore produced a
+  bridge file that could not resolve. `package.json`, `README.md`, and
+  `API.md` §1 now all say `zeus-css`.
+- **The four documented entry points now actually resolve.** README/`API.md` §1
+  document `zeus-css/foundation`, `zeus-css/zeus`, `zeus-css/config`, and
+  `zeus-css/customize`, but the generated package's `exports` map only carried
+  `.`, `./config`, and the raw `./scss/*` passthrough — so three of the four
+  documented specifiers failed to resolve against the published package.
+  Explicit aliases for all four are now emitted.
+- `$zeus-outer-padding` was declared twice in `zeus.config.scss` — an older
+  `(mobile, desktop)`-shaped default (used internally to auto-derive
+  `$container-bounds`) and a newer `(floor, ceil)`-shaped default (the public
+  config that drives `--padding-outer`) reused the same variable name. Because
+  the first `!default` assignment wins, the second declaration was always
+  dead: `--padding-outer` compiled with a `128px` → `64px` max instead of the
+  documented `128px`, and overriding the public var via its documented
+  `(floor, ceil)` shape crashed the build (`null` arithmetic) in
+  `core/design/core/basic.scss`. The internal default is now its own
+  variable, `$zeus-viewport-gutter` (the gutter between the viewport edge and
+  the container at each reference width), and both it and `$zeus-viewports`
+  (which was never forwarded at all) are now included in the `zeus-css init`
+  CLI bridge template.
+- **Six silent-failure gaps in the token pipeline, closed after an internal
+  audit.** All were "malformed override compiles anyway, producing broken CSS
+  or a confusing low-level error" — none were reachable through the shipped
+  defaults, only through a bad override:
+  - `_validate.scss`'s validators (written for exactly this) were never
+    `@include`d anywhere. Now wired into every token module that assembles a
+    `(floor, ceil)`/typography/button-size map — `design/dimensions/spaces.scss`,
+    `design/dimensions/sizes.scss`, `design/borders/border-radius.scss`,
+    `design/borders/border-line.scss`, `design/layout/grid.scss`
+    (`$column-gaps`), `design/typography/typography.scss`, and
+    `design/buttons/sizes.scss` — so a malformed entry now fails loudly, by
+    name, at the point it's declared.
+  - `zeus-resolve-type()` (`views/render/root-generator.scss`) duck-typed the
+    token pipeline's dictionary by checking for `floor`+`ceil` or
+    `weight`+`lh`; a map with only one of either pair silently fell through to
+    "nested map" and emitted a wrong CSS variable instead of the intended one.
+    Now `@error`s on a partial match, for any dictionary entry — not just the
+    six categories the validators above cover.
+  - `zeus-transform-value()`'s typography branch resolved a token's `family`
+    key against `$font-family` with no existence check, so a typo'd family
+    silently compiled a literal `null` into the emitted `font` shorthand. Now
+    `@error`s with the available family names.
+  - `btn-size()`'s missing-nested-key case (a size entry with `font`/`py`/`px`
+    present but no `floor`/`ceil` inside) is now unreachable — the
+    `design/buttons/sizes.scss` validator above rejects the malformed
+    `$zeus-button-sizes` entry before `btn-size()` ever sees it.
+  - `_c()` (`design/colors/semantic-colors.scss`) intentionally falls back to
+    a built-in default when a `$zeus-colors` key is absent — but that made a
+    typo'd key (e.g. `primry`) indistinguishable from "not set", with no
+    signal at all. `$zeus-colors` is now checked against the exact set of keys
+    this file reads; an unrecognized key `@warn`s by name instead of vanishing
+    silently.
+  - The custom-vars responsive loop (`zeus-root-vars()`) assumed
+    `$zeus-breakpoints` was already in ascending pixel order and iterated it
+    as-written; an override that appended a new breakpoint out of numeric
+    order would cascade it last instead of where its pixel value puts it. The
+    loop now sorts breakpoint keys by pixel value before iterating.
+- Duplicate `.inset-0` rule (one hardcoded, one loop-generated) in the new
+  position utilities.
+- `_form.scss`'s `&:hover:not(:disabled):not(:focus-visible)` rewritten to
+  the `:not(a, b)` complex-selector notation required by the new lint config.
+
+## [0.9.0] — 2026-07-20
+
+First public beta. Prior versions were internal-only; this changelog starts
+here rather than reconstructing an inaccurate pre-history.
+
+### Added
+- `LICENSE` (MIT), `package.json` with a proper `exports` map, and this
+  `CHANGELOG.md` — the framework can now be installed via npm.
+- `README.md` with install instructions and a 5-minute quickstart.
+- Opt-in `.no-overflow-x` utility (replaces the old global `overflow-x: hidden`
+  on `html`/`body`, which hid real layout overflow instead of surfacing it).
+- `@warn` diagnostic when `$zeus-breakpoint-strategy` is set to an
+  unimplemented value (previously silently ignored).
+
+### Changed
+- **Single source of truth for color tokens.** Any `*-light`, `*-dark`,
+  `surface`, `text-inverse`, `text-muted`, `border`, or `border-strong` key
+  defined in `$zeus-colors` is now respected as-is; automatic OKLCH derivation
+  only runs for keys the developer did **not** define. Previously, derived
+  values silently overwrote explicit config values.
+- Cascade layer order (`reset, tokens, base, layout, components, utilities`)
+  is now established before any layer receives rules, and `html`/`body`,
+  typography defaults, components (`.z-card`, `.z-modal`), and patterns
+  (`.z-hero`, `.z-sidebar-layout`) are now emitted inside their proper layer —
+  utility classes can reliably override component styles without `!important`.
+- `zeus.scss` (the module-only entry point used via `@use "zeus" as *` in
+  component files) is now truly zero-emission: animation `@keyframes` and the
+  scroll-driven `.z-scroll-*` classes moved to the render layer, so importing
+  it no longer leaks ~150 lines of duplicate CSS into every component.
+- Config schema unified to `(floor, ceil)` everywhere. `$zeus-column-gaps` and
+  `$zeus-outer-padding` previously used `(min, max)` keys that the engine
+  silently ignored — overrides now apply correctly.
+- Grid utilities (`.grid-cols-*`, `.grid-split`, `.grid-thirds`,
+  `.grid-sidebar`, `.z-sidebar-layout`) use `minmax(0, 1fr)` instead of bare
+  `1fr`, preventing grid blowout (a page-level horizontal scrollbar) when a
+  grid child contains wide unbreakable content such as code blocks.
+- `$zeus-use-prefix` now applies consistently across every utility generator
+  (shadows, containers, compounds, aspect-ratio, animations, grid patterns) —
+  previously only some class families respected it.
+- `color()` alpha blending now uses `color.change()` instead of `rgba()`,
+  which crashed on OKLCH input in modern Dart Sass.
+
+### Fixed
+- `<dialog class="z-modal">` no longer renders visible when closed (the base
+  rule set `display` unconditionally; it's now scoped to `&[open]`).
+- `:where(li) { list-style: none }` and the accompanying `padding-left: 0`
+  reset — both applied globally — have been removed; only lists explicitly
+  marked `[role="list"]` opt out of native bullets, preserving list semantics
+  for assistive technology.
+- `outline: none` on shadow-based focus styles now only applies under
+  `:focus-visible`, never plain `:focus`, so keyboard users always retain a
+  visible focus indicator.
+- `html { font-size: 16px }` → `font-size: 100%`, respecting the user's
+  browser font-size preference instead of overriding it.
+- `scroll-behavior: smooth` no longer applied unconditionally outside the
+  `prefers-reduced-motion` guard already present in the reset.
+- `--color-surface-subtle` and `--color-warning-subtle` (referenced by
+  `:where(code)` / `:where(mark)`) are now actually defined.
+- An impossible/dead media query combination
+  (`min-width: 2560px` together with an inner `max-width` below it) that could
+  never match has been removed from the responsive utility loop.
+- Stale `(min, max)` references in comments and validator error messages
+  corrected to the actual `(floor, ceil)` schema.

package/scss/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stavros Kosmas Lazaris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/scss/README.md

@@ -0,0 +1,160 @@
+# ⚡ Zeus CSS
+
+Zeus is a fluid-first SCSS design system. Every size, space, and font size scales
+smoothly between a mobile floor and a desktop ceiling using native CSS
+`clamp()` driven by container-query units (`cqi`) — no breakpoint jumps, no
+`calc()` guesswork. Colors are OKLCH-based semantic tokens with automatic
+light/dark derivation. The whole system is expressed as plain Sass maps, which
+makes it easy for both humans and AI coding assistants to read, extend, and
+reason about.
+
+- **Fluid by default** — `clamp()` scaling for spacing, type, radii, borders, icons.
+- **Semantic OKLCH tokens** — define 5 base colors, get light/dark/muted/border variants derived automatically.
+- **Cascade layers** — `reset → tokens → base → layout → components → utilities`, so utility classes always win without `!important`.
+- **Zero-emission module entry** — `@use "zeus" as *` in a component's `.module.scss` gives you every mixin/function with **no** leaked CSS.
+- **Config-first** — every token lives in one file you can override; nothing is hardcoded past that boundary.
+
+## Browser support
+
+Zeus targets evergreen browsers only — there is no fallback path for the core
+and none is planned. There is no IE11, no legacy Safari, and no polyfill
+story: if you need to support browsers older than ~2023, Zeus is not the
+right choice.
+
+**Required (the whole framework depends on these).** Cascade layers
+(`@layer`), container query units (`cqi`, `container-type`), `@property`,
+relative color syntax (`oklch(from …)`), `:has()`, `color-mix()`. All are
+Baseline "Widely available" in current Chrome/Edge, Firefox, and Safari.
+
+**Progressive enhancement (a few components use these and degrade if
+absent).** These are *not* uniformly Baseline — check current support for
+your targets rather than assuming:
+
+| Feature | Used by | Without it you get |
+| --- | --- | --- |
+| `popover` attribute | `.z-tooltip`, `.z-dropdown`, `.z-toast-region` | No top-layer rendering or light-dismiss — these three need it to function; verify support before relying on them |
+| CSS anchor positioning (`position-anchor`, `position-area`) | `.z-tooltip`, `.z-dropdown` | Still a fully working popover, just placed by the UA default instead of anchored to its trigger |
+| `@starting-style`, `transition-behavior: allow-discrete` | `.z-tooltip`, `.z-dropdown` enter/exit | Instant show/hide instead of a fade — purely cosmetic |
+
+Anchor positioning has the narrowest support of the three (Chromium shipped
+it well ahead of the other engines). The components are written so its
+absence costs placement, never functionality.
+
+## Install
+
+```bash
+npm install zeus-css
+```
+
+## Two entry points
+
+Zeus ships two distinct ways to consume it — pick the right one per file.
+
+### 1. Global stylesheet — `foundation`
+
+Import **once**, at your app root. Emits the full compiled CSS: reset, design
+tokens as CSS custom properties, typography base, and every utility class
+(`.padding-lg`, `.text-h1`, `.grid-cols-3`, …).
+
+```scss
+// app/globals.scss
+@use "zeus-css/foundation";
+```
+
+### 2. Component modules — `zeus`
+
+Import in **every** `.module.scss` component file. Exposes all mixins and
+functions (`@include padding(...)`, `@include text(...)`, `color(...)`, …) but
+emits **zero** CSS of its own — only the rules you actually write.
+
+```scss
+// Button.module.scss
+@use "zeus-css/zeus" as *;
+
+.button {
+  @include padding("md", "x");
+  @include text("button");
+  @include border-radius("sm");
+  background: color("primary");
+  color: var(--color-text-inverse);
+
+  &:hover {
+    background: color("primary-dark");
+  }
+}
+```
+
+## 5-minute quickstart
+
+```scss
+// 1. app/globals.scss — load the framework once
+@use "zeus-css/foundation";
+```
+
+```tsx
+// 2. app/layout.tsx — import the global stylesheet
+import "./globals.scss";
+```
+
+```scss
+// 3. components/Card.module.scss — build a component with the API
+@use "zeus-css/zeus" as *;
+
+.card {
+  @include padding("lg");
+  @include border-radius("md");
+  @include card-shadow();
+  background: var(--color-surface);
+  border: var(--border-line-xs) solid var(--color-border);
+}
+
+.title {
+  @include text("h4");
+  color: var(--color-text);
+}
+```
+
+```tsx
+// components/Card.tsx
+import styles from "./Card.module.scss";
+
+export function Card({ children }: { children: React.ReactNode }) {
+  return <div className={styles.card}>{children}</div>;
+}
+```
+
+That's it — no build config, no PostCSS plugin. Zeus compiles with any
+standard Dart Sass pipeline (Next.js, Vite, webpack `sass-loader`, or the
+`sass` CLI directly).
+
+## Theming your brand
+
+Every visual token — colors, typography, spacing, radii, shadows, breakpoints
+— lives in **one file**: `zeus.customize.scss`. Copy the keys you want to
+override from `zeus.token.sets.example.scss` (a reference-only file, never
+imported) into your own `zeus.customize.scss` before the `@use` chain resolves.
+
+```scss
+// zeus.customize.scss
+$zeus-colors: (
+  "primary": oklch(60% 0.2 250),
+  "primary-light": oklch(75% 0.15 250),
+  "primary-dark": oklch(45% 0.25 250),
+  // ...
+);
+```
+
+Layout/engine behavior (prefixing, responsive strategy, fluid viewport bounds)
+lives in `zeus.config.scss` — separate from design tokens on purpose, so
+brand changes and structural changes never collide in the same diff.
+
+## Learn more
+
+- `zeus.token.sets.example.scss` — full reference of every default token value.
+- `CHANGELOG.md` — what changed between versions.
+- The framework's docs site (component gallery, `/tokens-reference`, full API
+  reference) already exists in this monorepo — see `API.md` §6.
+
+## License
+
+MIT © Stavros Kosmas Lazaris