zeus-css 1.0.11 → 1.0.12

package/scss/CHANGELOG.md

@@ -1,299 +0,0 @@
-# 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]
-
-## [1.0.11] — 2026-08-05
-
-### Fixed
-- **The published package's README (generated by `scripts/build-package.ts`,
-  not copied from this file) documented Step 1 (`zeus-css/dist/zeus.css`) and
-  Step 2 (`npx zeus-css init` + `zeus.theme.css`) with no statement that
-  they're mutually exclusive** — a dev following both in sequence ended up
-  with both imports in the same root layout. Added an explicit warning plus
-  a two-line flowchart between the two steps in that template, so the
-  generated README (and every future publish) states the replacement
-  relationship instead of leaving it implied.
-
-## [1.0.10] — 2026-08-05
-
-Published to npm as `zeus-css`. [`API.md`](API.md) documents the public API
-surface this changelog's semver contract is now binding against.
-
-### 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.
-- **`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 existed — corrected to stop 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-css/css` and `zeus-css/min` were real, shipped exports
-  (`package.json` → `exports`) with no entry in README or `API.md` §1** — a
-  dev with no Sass pipeline had no documented way to just import the
-  precompiled CSS, and the two specifiers carried no semver contract despite
-  already being public. README now leads with them for the no-build-step
-  path; `API.md` §1 lists both, with a note that they're static builds of
-  `foundation.scss` with default tokens baked in and cannot reflect
-  `zeus.customize.scss` overrides.
-- `$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.