@astronox/core 0.5.11 → 0.5.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [

package/src/components/actions/ThemeToggle/ThemeToggle.astro

@@ -2,11 +2,13 @@
 import type { HTMLAttributes } from 'astro/types';
 import DayIcon from '../../icons/DayIcon.astro';
 import NightIcon from '../../icons/NightIcon.astro';
+import PumpkinIcon from '../../icons/PumpkinIcon.astro';
 
 type Props = HTMLAttributes<'button'> & {
   appearance?: 'circle' | 'utility';
   darkLabel: string;
   lightLabel: string;
+  halloweenLabel?: string;
 };
 
 const {
@@ -14,6 +16,7 @@ const {
   class: className,
   darkLabel,
   lightLabel,
+  halloweenLabel,
   type = 'button',
   ...attrs
 }: Props = Astro.props;
@@ -29,6 +32,7 @@ const {
   data-theme-toggle-appearance={appearance}
   data-theme-toggle-dark-label={darkLabel}
   data-theme-toggle-light-label={lightLabel}
+  data-theme-toggle-halloween-label={halloweenLabel}
   data-navigation-control={appearance === 'circle' ? '' : undefined}
   data-navigation-control-appearance={appearance === 'circle'
     ? 'bar'
@@ -48,6 +52,13 @@ const {
   >
     <DayIcon />
   </span>
+  <span
+    class="theme-toggle__icon"
+    data-theme-toggle-target="halloween"
+    aria-hidden="true"
+  >
+    <PumpkinIcon />
+  </span>
 </button>
 
 <script>

package/src/components/actions/ThemeToggle/ThemeToggle.css

@@ -49,15 +49,16 @@
   block-size: 100%;
 }
 
-.theme-toggle [data-theme-toggle-target='light'] {
+.theme-toggle [data-theme-toggle-target] {
   display: none;
 }
 
-:root[data-theme='dark'] .theme-toggle [data-theme-toggle-target='dark'] {
-  display: none;
-}
-
-:root[data-theme='dark'] .theme-toggle [data-theme-toggle-target='light'] {
+:root:not([data-next-theme]) .theme-toggle [data-theme-toggle-target='dark'],
+:root[data-next-theme='dark'] .theme-toggle [data-theme-toggle-target='dark'],
+:root[data-next-theme='light'] .theme-toggle [data-theme-toggle-target='light'],
+:root[data-next-theme='halloween']
+  .theme-toggle
+  [data-theme-toggle-target='halloween'] {
   display: grid;
 }
 

package/src/components/actions/ThemeToggle/themeToggleController.ts

@@ -1,114 +1,33 @@
-import type { ColorTheme } from '../../../theme/contracts';
-import { defaultThemeStorageKey } from '../../../theme/storage';
+import type { ThemeRuntime } from '../../../theme/runtime';
 
 const initializedToggles = new WeakSet<HTMLElement>();
-const systemThemeQuery = '(prefers-color-scheme: dark)';
-let globalListenersInitialized = false;
-
-function isColorTheme(value: string | null): value is ColorTheme {
-  return value === 'light' || value === 'dark';
-}
-
-function getStorageKey(): string {
-  return (
-    document.documentElement.dataset.themeStorageKey ?? defaultThemeStorageKey
-  );
-}
-
-function readStoredTheme(): ColorTheme | null {
-  try {
-    const value = window.localStorage.getItem(getStorageKey());
-    return isColorTheme(value) ? value : null;
-  } catch {
-    return null;
-  }
-}
-
-function getSystemTheme(): ColorTheme {
-  return window.matchMedia(systemThemeQuery).matches ? 'dark' : 'light';
-}
-
-function getCurrentTheme(): ColorTheme {
-  const value = document.documentElement.dataset.theme ?? null;
-  return isColorTheme(value) ? value : (readStoredTheme() ?? getSystemTheme());
-}
-
-function updateToggle(toggle: HTMLElement, theme: ColorTheme): void {
-  const label =
-    theme === 'light'
-      ? toggle.dataset.themeToggleDarkLabel
-      : toggle.dataset.themeToggleLightLabel;
-
-  if (label) {
-    toggle.setAttribute('aria-label', label);
-    toggle.setAttribute('title', label);
-  }
-}
-
-function updateToggles(theme: ColorTheme): void {
-  for (const toggle of document.querySelectorAll<HTMLElement>(
-    '[data-theme-toggle]',
-  )) {
-    updateToggle(toggle, theme);
-  }
-}
-
-function applyTheme(theme: ColorTheme, persist: boolean): void {
-  const root = document.documentElement;
-  root.dataset.themeSwitching = 'true';
-  root.dataset.theme = theme;
-  void root.offsetWidth;
-  delete root.dataset.themeSwitching;
-
-  if (persist) {
-    try {
-      window.localStorage.setItem(getStorageKey(), theme);
-    } catch {
-      // The selected theme remains active for the current document.
-    }
-  }
-
-  updateToggles(theme);
-  document.dispatchEvent(
-    new CustomEvent('astronox:theme-change', { detail: { theme } }),
-  );
-}
-
-function initializeGlobalListeners(): void {
-  if (globalListenersInitialized) return;
-  globalListenersInitialized = true;
-
-  const media = window.matchMedia(systemThemeQuery);
-  media.addEventListener('change', (event) => {
-    if (readStoredTheme() === null) {
-      applyTheme(event.matches ? 'dark' : 'light', false);
-    }
-  });
-
-  window.addEventListener('storage', (event) => {
-    if (event.key !== getStorageKey()) return;
-
-    const theme = isColorTheme(event.newValue)
-      ? event.newValue
-      : getSystemTheme();
-    applyTheme(theme, false);
-  });
-}
 
 export function initThemeToggle(toggle: HTMLElement): () => void {
   if (initializedToggles.has(toggle)) return () => {};
+  const runtime: ThemeRuntime | undefined = window.__astronoxTheme;
+  if (!runtime) return () => {};
   initializedToggles.add(toggle);
-  initializeGlobalListeners();
-  updateToggle(toggle, getCurrentTheme());
 
-  const handleClick = (): void => {
-    applyTheme(getCurrentTheme() === 'light' ? 'dark' : 'light', true);
+  const update = (): void => {
+    const labels = {
+      light: toggle.dataset.themeToggleLightLabel,
+      dark: toggle.dataset.themeToggleDarkLabel,
+      halloween: toggle.dataset.themeToggleHalloweenLabel,
+    };
+    const label = labels[runtime.next()];
+    if (!label) return;
+    toggle.setAttribute('aria-label', label);
+    toggle.setAttribute('title', label);
   };
+  const handleClick = (): void => runtime.cycle();
 
+  update();
   toggle.addEventListener('click', handleClick);
+  document.addEventListener('astronox:theme-change', update);
 
   return () => {
     toggle.removeEventListener('click', handleClick);
+    document.removeEventListener('astronox:theme-change', update);
     initializedToggles.delete(toggle);
   };
 }

package/src/components/feedback/SeasonalDecorations/SeasonalDecorations.astro

@@ -0,0 +1,60 @@
+---
+const drips = [
+  {
+    x: 'calc(var(--nox-page-gutter) / 2)',
+    length: 34,
+    delay: 0,
+    edge: true,
+  },
+  { x: '14%', length: 22, delay: 2000, edge: false },
+  { x: '29%', length: 39, delay: 6000, edge: false },
+  { x: '47%', length: 26, delay: 10000, edge: false },
+  { x: '66%', length: 32, delay: 4000, edge: false },
+  { x: '83%', length: 20, delay: 8000, edge: false },
+  {
+    x: 'calc(100% - var(--nox-page-gutter) / 2)',
+    length: 42,
+    delay: 4000,
+    edge: true,
+  },
+];
+---
+
+<div class="seasonal-decorations" aria-hidden="true" inert>
+  {
+    drips.map(({ x, length, delay, edge }) => (
+      <div
+        class="seasonal-decorations__drip"
+        data-drip-edge={edge ? '' : undefined}
+        style={`--drip-x: ${x}; --drip-length: ${length}px; --drip-delay: ${delay}ms;`}
+      >
+        <svg
+          viewBox="0 0 24 48"
+          preserveAspectRatio="none"
+          fill="currentColor"
+          focusable="false"
+        >
+          <path d="M0 0H24C18 2 17 5 17 13V33C17 43 15 48 12 48S7 43 7 33V13C7 5 6 2 0 0Z" />
+        </svg>
+        <span class="seasonal-decorations__drop" />
+      </div>
+    ))
+  }
+  {
+    ['start', 'end'].map((side) => (
+      <svg
+        class="seasonal-decorations__web"
+        data-web-side={side}
+        viewBox="0 0 120 120"
+        fill="none"
+        focusable="false"
+      >
+        <path
+          d="M0 0V116M0 0L43 110M0 0L85 85M0 0L110 43M0 0H116M0 24Q7 21 9 23Q15 16 17 17Q21 8 23 9Q22 4 24 0M0 48Q13 43 18 46Q28 33 34 34Q41 20 46 18Q42 7 48 0M0 77Q22 68 29 72Q47 51 54 54Q65 35 72 29Q68 14 77 0M0 108Q30 93 40 101Q64 71 76 76Q90 49 101 40Q92 20 108 0"
+          stroke="currentColor"
+          stroke-width="1"
+        />
+      </svg>
+    ))
+  }
+</div>

package/src/components/feedback/SeasonalDecorations/SeasonalDecorations.css

@@ -0,0 +1,134 @@
+.seasonal-decorations {
+  --seasonal-decoration-top: calc(
+    var(--nox-site-header-compact-height) + var(--nox-seasonal-border-size)
+  );
+
+  position: fixed;
+  z-index: -1;
+  inset: var(--seasonal-decoration-top) 0 0;
+  display: none;
+  overflow: hidden;
+  scrollbar-gutter: inherit;
+  pointer-events: none;
+  user-select: none;
+  color: var(--nox-seasonal-blood);
+}
+
+:root[data-appearance='halloween']:is(
+    [data-theme-decorations='static'],
+    [data-theme-decorations='animated']
+  )
+  .seasonal-decorations {
+  display: block;
+}
+
+.seasonal-decorations__drip {
+  --drip-period: 12s;
+
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-start: var(--drip-x);
+  inline-size: 18px;
+  block-size: var(--drip-length);
+  transform: translateX(-50%);
+}
+
+.seasonal-decorations__drip[data-drip-edge] {
+  --drip-period: 8s;
+}
+
+.seasonal-decorations__drip > svg {
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+}
+
+.seasonal-decorations__drop {
+  position: absolute;
+  inset-block-start: calc(100% - 8px);
+  inset-inline-start: 5px;
+  inline-size: 8px;
+  block-size: 13px;
+  border-radius: 45% 45% 55% 55%;
+  background: var(--nox-seasonal-blood);
+  opacity: 0;
+  transform-origin: top;
+}
+
+.seasonal-decorations__web {
+  position: absolute;
+  inset-block-start: 0;
+  inline-size: clamp(3rem, 7vw, 7rem);
+  block-size: auto;
+  color: var(--nox-seasonal-web);
+  opacity: 0.35;
+}
+
+.seasonal-decorations__web[data-web-side='start'] {
+  inset-inline-start: 0;
+}
+
+.seasonal-decorations__web[data-web-side='end'] {
+  inset-inline-end: 0;
+  transform: scaleX(-1);
+}
+
+@media (width >= 72rem) {
+  .seasonal-decorations {
+    --seasonal-decoration-top: calc(
+      var(--nox-site-header-height) - var(--nox-border-width) +
+        var(--nox-seasonal-border-size)
+    );
+  }
+}
+
+@media (width < 48rem) {
+  .seasonal-decorations__drip {
+    block-size: calc(var(--drip-length) * 0.65);
+    inline-size: 14px;
+  }
+
+  .seasonal-decorations__drip:not([data-drip-edge]) {
+    display: none;
+  }
+
+  .seasonal-decorations__drop {
+    inset-inline-start: 3px;
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  :root[data-appearance='halloween'][data-theme-decorations='animated']
+    .seasonal-decorations__drop {
+    animation: seasonal-blood-fall var(--drip-period) linear var(--drip-delay)
+      infinite both;
+    animation-play-state: var(--seasonal-animation-state, running);
+  }
+}
+
+:root[data-theme-animation-paused] .seasonal-decorations {
+  --seasonal-animation-state: paused;
+}
+
+@keyframes seasonal-blood-fall {
+  0% {
+    opacity: 0;
+    transform: translateY(0) scale(0.5, 0.2);
+  }
+
+  4% {
+    opacity: 1;
+    transform: translateY(0) scale(1, 1.15);
+  }
+
+  8% {
+    opacity: 1;
+    transform: translateY(20px) scale(0.85, 1.3);
+  }
+
+  25%,
+  100% {
+    opacity: 0;
+    transform: translateY(min(65vh, 30rem)) scale(0.75, 1.4);
+  }
+}

package/src/components/feedback/ThemeBootstrap/ThemeBootstrap.astro

@@ -1,31 +1,212 @@
 ---
 import { defaultThemeStorageKey } from '../../../theme/storage';
+import type { SeasonalThemeConfig } from '../../../theme/contracts';
 
 type Props = {
   storageKey?: string;
+  seasonalTheme?: SeasonalThemeConfig;
 };
 
-const { storageKey = defaultThemeStorageKey }: Props = Astro.props;
+const { storageKey = defaultThemeStorageKey, seasonalTheme }: Props =
+  Astro.props;
 ---
 
-<script is:inline define:vars={{ storageKey }}>
+<script
+  is:inline
+  define:vars={{ storageKey, seasonalTheme: seasonalTheme ?? null }}
+>
   (() => {
+    window.__astronoxTheme?.destroy();
     const root = document.documentElement;
-    let storedTheme = null;
+    const seasonalKey = `${storageKey}:seasonal`;
+    const media = window.matchMedia?.('(prefers-color-scheme: dark)');
+    let choices = ['light', 'dark'];
+    let activeEventId = null;
+    let boundaryTimeout;
 
-    try {
-      const value = window.localStorage.getItem(storageKey);
-      if (value === 'light' || value === 'dark') storedTheme = value;
-    } catch {
-      // The system preference remains available without local storage.
-    }
+    const resolveSeason = (now) => {
+      if (!seasonalTheme) return { id: null, boundary: null };
+      const period = seasonalTheme.annualPeriod;
+      if (!period) return { id: seasonalTheme.id, boundary: null };
 
-    const systemTheme = window.matchMedia?.('(prefers-color-scheme: dark)')
-      .matches
-      ? 'dark'
-      : 'light';
+      const spansNewYear =
+        period.start.month * 100 + period.start.day >
+        period.end.month * 100 + period.end.day;
+      const year = now.getFullYear();
+      for (const startYear of [year - 1, year, year + 1]) {
+        const start = new Date(
+          startYear,
+          period.start.month - 1,
+          period.start.day,
+        );
+        const end = new Date(
+          startYear + Number(spansNewYear),
+          period.end.month - 1,
+          period.end.day,
+        );
+        if (now < start) return { id: null, boundary: start.getTime() };
+        if (now < end) {
+          return {
+            id: `${seasonalTheme.id}-${startYear}`,
+            boundary: end.getTime(),
+          };
+        }
+      }
+      return { id: null, boundary: null };
+    };
+
+    const read = (key) => {
+      try {
+        return window.localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    };
+    const write = (key, value) => {
+      try {
+        window.localStorage.setItem(key, value);
+      } catch {
+        // Keep the document's choice when browser storage is unavailable.
+      }
+    };
+    const readClassic = () => {
+      const value = read(storageKey);
+      return value === 'light' || value === 'dark' ? value : null;
+    };
+    const readSeasonal = () => {
+      if (!activeEventId) return null;
+      try {
+        const value = JSON.parse(read(seasonalKey) ?? 'null');
+        if (
+          value?.id === activeEventId &&
+          (value.choice === 'seasonal' || value.choice === 'classic')
+        ) {
+          return value.choice;
+        }
+      } catch {
+        // An invalid or older event preference does not disable a new event.
+      }
+      return null;
+    };
+    const saveSeasonal = (choice) => {
+      if (!activeEventId) return;
+      write(seasonalKey, JSON.stringify({ id: activeEventId, choice }));
+    };
+
+    let classic = readClassic();
+    let seasonal = null;
+    let current;
+
+    const handleVisibility = () => {
+      root.toggleAttribute('data-theme-animation-paused', document.hidden);
+      if (!document.hidden) reconcile();
+    };
+    const next = () => choices[(choices.indexOf(current) + 1) % choices.length];
+    const resolve = () =>
+      activeEventId && seasonal === 'seasonal'
+        ? seasonalTheme.appearance
+        : (classic ?? (media?.matches ? 'dark' : 'light'));
+    const apply = () => {
+      const appearance = resolve();
+      const appearanceChanged = current !== appearance;
+      const theme = appearance === 'light' ? 'light' : 'dark';
+      const decorations = activeEventId
+        ? (seasonalTheme.decorations ?? 'none')
+        : 'none';
+      if (appearanceChanged) root.dataset.themeSwitching = 'true';
+      root.dataset.theme = theme;
+      root.dataset.appearance = appearance;
+      current = appearance;
+      const nextTheme = next();
+      const controlsChanged =
+        root.dataset.nextTheme !== nextTheme ||
+        root.dataset.themeDecorations !== decorations;
+      root.dataset.nextTheme = nextTheme;
+      root.dataset.themeDecorations = decorations;
+      root.toggleAttribute(
+        'data-theme-animation-paused',
+        document.hidden && decorations === 'animated',
+      );
+      if (appearanceChanged) {
+        void root.offsetWidth;
+        delete root.dataset.themeSwitching;
+      }
+      if (appearanceChanged || controlsChanged) {
+        document.dispatchEvent(
+          new CustomEvent('astronox:theme-change', {
+            detail: { theme, appearance },
+          }),
+        );
+      }
+    };
+    const reconcile = () => {
+      const now = new Date();
+      const season = resolveSeason(now);
+      if (activeEventId !== season.id) {
+        activeEventId = season.id;
+        seasonal = readSeasonal();
+      }
+      if (activeEventId && seasonal === null) {
+        seasonal = 'seasonal';
+        saveSeasonal(seasonal);
+      }
+      choices = activeEventId
+        ? ['light', 'dark', seasonalTheme.appearance]
+        : ['light', 'dark'];
+      clearTimeout(boundaryTimeout);
+      if (season.boundary !== null) {
+        boundaryTimeout = setTimeout(
+          reconcile,
+          Math.min(season.boundary - now.getTime(), 2_147_483_647),
+        );
+      }
+      apply();
+    };
+    const cycle = () => {
+      reconcile();
+      const appearance = next();
+      if (appearance === 'light' || appearance === 'dark') {
+        classic = appearance;
+        write(storageKey, classic);
+        seasonal = 'classic';
+      } else {
+        seasonal = 'seasonal';
+      }
+      saveSeasonal(seasonal);
+      apply();
+    };
+    const handleStorage = (event) => {
+      if (
+        event.key !== null &&
+        event.key !== storageKey &&
+        event.key !== seasonalKey
+      ) {
+        return;
+      }
+      classic = readClassic();
+      seasonal = readSeasonal();
+      reconcile();
+    };
 
-    root.dataset.theme = storedTheme ?? systemTheme;
     root.dataset.themeStorageKey = storageKey;
+    window.__astronoxTheme = {
+      next,
+      cycle,
+      destroy: () => {
+        clearTimeout(boundaryTimeout);
+        media?.removeEventListener('change', reconcile);
+        document.removeEventListener('visibilitychange', handleVisibility);
+        delete root.dataset.themeAnimationPaused;
+        window.removeEventListener('storage', handleStorage);
+        window.removeEventListener('focus', reconcile);
+        window.removeEventListener('pageshow', reconcile);
+      },
+    };
+    media?.addEventListener('change', reconcile);
+    document.addEventListener('visibilitychange', handleVisibility);
+    window.addEventListener('storage', handleStorage);
+    window.addEventListener('focus', reconcile);
+    window.addEventListener('pageshow', reconcile);
+    reconcile();
   })();
 </script>

package/src/components/icons/DayIcon.astro

@@ -23,11 +23,15 @@ const {
   aria-hidden={ariaHidden}
   focusable={focusable}
 >
-  <circle cx="16" cy="16" r="4" stroke="currentColor" stroke-width="1.5"
-  ></circle>
-  <path
-    d="M16 8v2M16 22v2M8 16h2M22 16h2M10.35 10.35l1.4 1.4M20.25 20.25l1.4 1.4M21.65 10.35l-1.4 1.4M11.75 20.25l-1.4 1.4"
+  <g
     stroke="currentColor"
     stroke-width="1.5"
-    stroke-linecap="round"></path>
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <circle cx="16" cy="16" r="4.5"></circle>
+    <path
+      d="M16 7v2M16 23v2M7 16h2M23 16h2M9.64 9.64l1.41 1.41M20.95 20.95l1.41 1.41M22.36 9.64l-1.41 1.41M11.05 20.95l-1.41 1.41"
+    ></path>
+  </g>
 </svg>

package/src/components/icons/NightIcon.astro

@@ -23,10 +23,12 @@ const {
   aria-hidden={ariaHidden}
   focusable={focusable}
 >
-  <path
-    d="M22.5 19.25A7.5 7.5 0 0 1 12.75 9.5a7.5 7.5 0 1 0 9.75 9.75Z"
+  <g
     stroke="currentColor"
     stroke-width="1.5"
     stroke-linecap="round"
-    stroke-linejoin="round"></path>
+    stroke-linejoin="round"
+  >
+    <path d="M25 16.8A9 9 0 1 1 15.2 7A7 7 0 0 0 25 16.8Z"></path>
+  </g>
 </svg>

package/src/components/icons/PumpkinIcon.astro

@@ -0,0 +1,37 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+
+type Props = HTMLAttributes<'svg'>;
+
+const {
+  width = 32,
+  height = 32,
+  'aria-hidden': ariaHidden = 'true',
+  focusable = 'false',
+  ...attrs
+}: Props = Astro.props;
+---
+
+<svg
+  {...attrs}
+  width={width}
+  height={height}
+  viewBox="0 0 32 32"
+  fill="none"
+  aria-hidden={ariaHidden}
+  focusable={focusable}
+>
+  <g
+    stroke="currentColor"
+    stroke-width="1.5"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path d="M16 11Q15 8 18 7"></path>
+    <path
+      d="M16 11C13 8.5 7 9.5 7 16C7 21 9.8 24.5 13 23.5Q16 25 19 23.5C22.2 24.5 25 21 25 16C25 9.5 19 8.5 16 11Z"
+    ></path>
+    <path d="M11 16.5l1.5-2 1.5 2ZM18 16.5l1.5-2 1.5 2Z"></path>
+    <path d="M12 19.5l2 1.5 2-1 2 1 2-1.5"></path>
+  </g>
+</svg>

package/src/components/index.ts

@@ -94,6 +94,7 @@ export { default as InfoIcon } from './icons/InfoIcon.astro';
 export { default as MinusIcon } from './icons/MinusIcon.astro';
 export { default as MountainIcon } from './icons/MountainIcon.astro';
 export { default as NightIcon } from './icons/NightIcon.astro';
+export { default as PumpkinIcon } from './icons/PumpkinIcon.astro';
 export { default as PlayIcon } from './icons/PlayIcon.astro';
 export { default as PlusIcon } from './icons/PlusIcon.astro';
 export { default as PoisonIcon } from './icons/PoisonIcon.astro';

package/src/components/navigation/Footer/Footer.astro

@@ -7,6 +7,7 @@ import ArrowRightIcon from '../../icons/ArrowRightIcon.astro';
 type Props = HTMLAttributes<'footer'> & {
   columnSeparator?: 'divider' | 'none';
   columns?: 1 | 2;
+  endSpacing?: 'default' | 'extended';
   groups: readonly FooterGroup[];
   label: string;
   tone?: Tone;
@@ -17,6 +18,7 @@ const {
   columnSeparator = 'none',
   columns = 1,
   'data-tone': dataTone,
+  endSpacing = 'default',
   groups,
   label,
   tone,
@@ -31,6 +33,7 @@ const resolveRel = (target: FooterItem['target'], rel?: FooterItem['rel']) =>
 <footer
   {...attrs}
   class:list={['site-footer', className]}
+  data-footer-end-spacing={endSpacing}
   data-tone={resolvedTone}
   data-widget="site-footer"
 >

package/src/components/navigation/Footer/Footer.css

@@ -2,6 +2,16 @@
   color: var(--nox-text-muted);
 }
 
+.site-footer[data-footer-end-spacing='extended'] {
+  --site-footer-end-reserve: calc(
+    clamp(10rem, 20vh, 16rem) + env(safe-area-inset-bottom, 0px)
+  );
+}
+
+:root[data-appearance='halloween'] .site-footer {
+  background: var(--nox-page-background);
+}
+
 .site-footer__content {
   --site-footer-item-gap: var(--nox-space-2);
   --site-footer-marker-gap: 0.0625rem;
@@ -12,7 +22,8 @@
   justify-items: center;
   gap: var(--nox-space-1);
   padding-block-end: calc(
-    var(--site-content-gap) + var(--site-floating-control-reserve, 0px)
+    var(--site-content-gap) + var(--site-floating-control-reserve, 0px) +
+      var(--site-footer-end-reserve, 0px)
   );
   font-size: var(--nox-font-size-sm);
   line-height: 1.25;

package/src/components/navigation/Header.css

@@ -4,10 +4,14 @@
     var(--nox-site-header-height) - var(--site-header-border-width)
   );
 
+  position: relative;
   z-index: 50;
   top: 0;
   border-bottom: var(--site-header-border-width) solid var(--nox-border);
-  background: color-mix(in srgb, var(--nox-surface) 94%, transparent);
+  background: var(
+    --nox-seasonal-header-background,
+    color-mix(in srgb, var(--nox-surface) 94%, transparent)
+  );
   backdrop-filter: blur(14px);
 }
 
@@ -15,6 +19,31 @@
   position: sticky;
 }
 
+:root[data-appearance='halloween']:is(
+    [data-theme-decorations='static'],
+    [data-theme-decorations='animated']
+  )
+  .site-header {
+  --site-header-menu-block-offset: var(--nox-seasonal-border-size);
+  --site-header-menu-border-width: 0px;
+  --dropdown-attached-block-offset: var(--site-header-menu-block-offset);
+  --dropdown-attached-border-top-width: var(--site-header-menu-border-width);
+}
+
+:root[data-appearance='halloween']:is(
+    [data-theme-decorations='static'],
+    [data-theme-decorations='animated']
+  )
+  .site-header::after {
+  position: absolute;
+  inset-inline: 0;
+  inset-block-start: 100%;
+  block-size: var(--nox-seasonal-border-size);
+  background: var(--nox-seasonal-blood);
+  content: '';
+  pointer-events: none;
+}
+
 .site-nav {
   position: relative;
 }

package/src/components/navigation/MobileNavigation.css

@@ -111,15 +111,22 @@
   z-index: 2;
   display: grid;
   inset-inline: 0;
-  top: 100%;
+  top: calc(100% + var(--site-header-menu-block-offset, 0px));
   width: 100%;
-  height: calc(100vh - var(--nox-site-header-compact-height));
-  height: calc(100dvh - var(--nox-site-header-compact-height));
+  height: calc(
+    100vh - var(--nox-site-header-compact-height) -
+      var(--site-header-menu-block-offset, 0px)
+  );
+  height: calc(
+    100dvh - var(--nox-site-header-compact-height) -
+      var(--site-header-menu-block-offset, 0px)
+  );
   grid-template-rows: minmax(0, 1fr) auto;
   overflow-x: hidden;
   overflow-y: hidden;
   padding: var(--nox-space-3);
-  border-top: 3px solid var(--nox-link-active);
+  border-top: var(--site-header-menu-border-width, 3px) solid
+    var(--nox-theme-accent-color, var(--nox-link-active));
   border-bottom: var(--nox-border-width) solid var(--nox-border);
   border-end-start-radius: var(--nox-radius-md);
   border-end-end-radius: var(--nox-radius-md);
@@ -160,7 +167,7 @@
   left: 0;
   height: 2px;
   border-radius: var(--nox-radius-pill);
-  background: var(--nox-source-tone-success);
+  background: var(--nox-theme-accent-color, var(--nox-source-tone-success));
   content: '';
 }
 

package/src/components/navigation/NavigationBrand.astro

@@ -36,9 +36,11 @@ const logoAspectRatio = logo ? `${logo.width} / ${logo.height}` : undefined;
       <div
         class="site-nav__brand-logo-frame"
         style={`--site-nav-brand-logo-aspect-ratio: ${logoAspectRatio};`}
+        data-brand-variants={Object.keys(logo.variants ?? {}).join(' ')}
       >
         <Media
           class="site-nav__brand-logo"
+          data-brand-appearance="default"
           media={{
             src: logo.src,
             alt: logo.alt,
@@ -50,6 +52,22 @@ const logoAspectRatio = logo ? `${logo.width} / ${logo.height}` : undefined;
           }}
           fit="contain"
         />
+        {Object.entries(logo.variants ?? {}).map(([appearance, src]) => (
+          <Media
+            class="site-nav__brand-logo"
+            data-brand-appearance={appearance}
+            media={{
+              src,
+              alt: logo.alt,
+              width: logo.width,
+              height: logo.height,
+              loading: 'eager',
+              decoding: 'sync',
+              fetchPriority: 'high',
+            }}
+            fit="contain"
+          />
+        ))}
       </div>
     ) : (
       <>

package/src/components/navigation/NavigationBrand.css

@@ -21,6 +21,37 @@
   aspect-ratio: var(--site-nav-brand-logo-aspect-ratio);
 }
 
+.site-nav__brand-logo[data-brand-appearance] {
+  grid-area: 1 / 1;
+}
+
+.site-nav__brand-logo[data-brand-appearance]:not(
+    [data-brand-appearance='default']
+  ) {
+  display: none;
+}
+
+:root[data-appearance='light']
+  .site-nav__brand-logo[data-brand-appearance='light'],
+:root[data-appearance='dark']
+  .site-nav__brand-logo[data-brand-appearance='dark'],
+:root[data-appearance='halloween']
+  .site-nav__brand-logo[data-brand-appearance='halloween'] {
+  display: grid;
+}
+
+:root[data-appearance='light']
+  .site-nav__brand-logo-frame[data-brand-variants~='light']
+  [data-brand-appearance='default'],
+:root[data-appearance='dark']
+  .site-nav__brand-logo-frame[data-brand-variants~='dark']
+  [data-brand-appearance='default'],
+:root[data-appearance='halloween']
+  .site-nav__brand-logo-frame[data-brand-variants~='halloween']
+  [data-brand-appearance='default'] {
+  display: none;
+}
+
 .site-nav__brand-logo-frame [data-widget='media'] {
   inline-size: 100%;
   block-size: 100%;

package/src/components/navigation/NavigationControl.css

@@ -110,7 +110,7 @@
   left: var(--nox-space-4);
   height: 3px;
   border-radius: var(--nox-radius-pill);
-  background: var(--nox-source-tone-success);
+  background: var(--nox-theme-accent-color, var(--nox-source-tone-success));
   content: '';
   opacity: 0;
   transform: translateY(var(--nox-space-1));

package/src/components/navigation/SubNavigation/SubNavigation.css

@@ -77,7 +77,7 @@
   inset-block-end: 0;
   height: 3px;
   border-radius: 0;
-  background: var(--nox-tone-text);
+  background: var(--nox-theme-accent-color, var(--nox-tone-text));
   content: '';
   opacity: 0;
   pointer-events: none;

package/src/components/seo/SeoHead.astro

@@ -101,20 +101,30 @@ const jsonLdNodes = [
 }
 <script is:inline>
   (() => {
-    const applyThemeColor = (theme) => {
-      if (theme !== 'light' && theme !== 'dark') return;
+    const applyThemeColor = (theme, appearance) => {
+      const candidates = [
+        ...document.querySelectorAll(
+          'meta[name="theme-color"][data-theme-color]',
+        ),
+      ];
+      const target = candidates.some(
+        (meta) => meta.dataset.themeColor === appearance,
+      )
+        ? appearance
+        : theme;
 
-      for (const meta of document.querySelectorAll(
-        'meta[name="theme-color"][data-theme-color]',
-      )) {
+      for (const meta of candidates) {
         if (!(meta instanceof HTMLMetaElement)) continue;
-        meta.media = meta.dataset.themeColor === theme ? 'all' : 'not all';
+        meta.media = meta.dataset.themeColor === target ? 'all' : 'not all';
       }
     };
 
-    applyThemeColor(document.documentElement.dataset.theme);
+    applyThemeColor(
+      document.documentElement.dataset.theme,
+      document.documentElement.dataset.appearance,
+    );
     document.addEventListener('astronox:theme-change', (event) => {
-      applyThemeColor(event.detail?.theme);
+      applyThemeColor(event.detail?.theme, event.detail?.appearance);
     });
   })();
 </script>

package/src/config/siteConfig.ts

@@ -1,5 +1,5 @@
 import type { PageMeta } from './pageMeta';
-import type { ColorTheme } from '../theme/contracts';
+import type { SeasonalThemeConfig, ThemeAppearance } from '../theme/contracts';
 
 export type SiteTextDirection = 'ltr' | 'rtl';
 
@@ -22,6 +22,7 @@ export type SiteIdentity = {
     alt: string;
     width: number;
     height: number;
+    variants?: Partial<Record<ThemeAppearance, string>>;
   };
 };
 
@@ -36,7 +37,7 @@ export type SiteIconConfig = {
 export type SiteThemeColor = {
   color: string;
   media?: string;
-  theme?: ColorTheme;
+  theme?: ThemeAppearance;
 };
 
 export type SiteSeoConfig = {
@@ -56,6 +57,7 @@ export type SiteSeoConfig = {
 
 export type SiteConfig = {
   identity: SiteIdentity;
+  seasonalTheme?: SeasonalThemeConfig;
   defaultLocale: string;
   locales: readonly [SiteLocaleConfig, ...SiteLocaleConfig[]];
   routing: {
@@ -75,6 +77,34 @@ export function defineSiteConfig<const TConfig extends SiteConfig>(
     throw new Error(`Invalid site identity: ${config.identity.id}`);
   }
 
+  if (config.seasonalTheme && !config.seasonalTheme.id.trim()) {
+    throw new Error('A seasonal theme requires a non-empty event id.');
+  }
+
+  const period = config.seasonalTheme?.annualPeriod;
+  if (period) {
+    for (const { month, day } of [period.start, period.end]) {
+      const date = new Date(Date.UTC(2001, month - 1, day));
+      if (
+        !Number.isInteger(month) ||
+        !Number.isInteger(day) ||
+        date.getUTCFullYear() !== 2001 ||
+        date.getUTCMonth() !== month - 1 ||
+        date.getUTCDate() !== day
+      ) {
+        throw new Error(
+          'Annual theme periods require month/day dates valid every year.',
+        );
+      }
+    }
+    if (
+      period.start.month === period.end.month &&
+      period.start.day === period.end.day
+    ) {
+      throw new Error('An annual theme period requires distinct boundaries.');
+    }
+  }
+
   const localeIds = new Set<string>();
   const urlCodes = new Set<string>();
 

package/src/layouts/BaseLayout.astro

@@ -11,6 +11,7 @@ import PageSurface from './PageSurface.astro';
 import Breadcrumbs from '../components/navigation/Breadcrumbs/Breadcrumbs.astro';
 import ScrollToTop from '../components/actions/ScrollToTop/ScrollToTop.astro';
 import ThemeBootstrap from '../components/feedback/ThemeBootstrap/ThemeBootstrap.astro';
+import SeasonalDecorations from '../components/feedback/SeasonalDecorations/SeasonalDecorations.astro';
 import { defaultThemeStorageKey } from '../theme/storage';
 
 type Props = HTMLAttributes<'html'> & {
@@ -51,7 +52,10 @@ const resolvedTone = tone ?? dataTone;
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <ThemeBootstrap storageKey={themeStorageKey} />
+    <ThemeBootstrap
+      storageKey={themeStorageKey}
+      seasonalTheme={site.seasonalTheme}
+    />
     <SeoHead
       breadcrumbs={breadcrumbs}
       meta={meta}
@@ -65,6 +69,7 @@ const resolvedTone = tone ?? dataTone;
     <div class="site-shell" data-site-scroll-root>
       <slot name="skip-link" />
       <slot name="header" />
+      {site.seasonalTheme?.decorations ? <SeasonalDecorations /> : null}
       <div class="site-viewport" data-site-viewport>
         <main id="content" class="site-main" tabindex="-1">
           <div class="site-main__content">

package/src/patterns/Dropdown/Dropdown.css

@@ -57,7 +57,7 @@
   padding: var(--nox-space-2) 0;
   gap: 0;
   border: var(--nox-border-width) solid var(--nox-border);
-  border-top: 3px solid var(--nox-link-active);
+  border-top: 3px solid var(--nox-theme-accent-color, var(--nox-link-active));
   border-radius: var(--nox-radius-md);
   background: var(--nox-surface);
   box-shadow: var(--nox-shadow-surface);
@@ -76,12 +76,21 @@
 .dropdown[data-dropdown-attached][data-dropdown-placement='bottom']
   .dropdown__content {
   top: calc(100% + var(--dropdown-attached-block-offset, 0px));
-  border-top: 3px solid var(--nox-link-active);
+  border-top-width: var(--dropdown-attached-border-top-width, 3px);
   border-start-start-radius: 0;
   border-start-end-radius: 0;
   box-shadow: none;
 }
 
+.dropdown[data-dropdown-attached][data-dropdown-placement='bottom'][data-dropdown-open]::before {
+  position: absolute;
+  z-index: 90;
+  inset-inline: 0;
+  inset-block-start: 100%;
+  block-size: var(--dropdown-attached-block-offset, 0px);
+  content: '';
+}
+
 .dropdown[data-dropdown-placement='top'] .dropdown__content {
   bottom: calc(100% + var(--nox-space-2));
 }

package/src/patterns/StageFlow/StageFlowStage.css

@@ -4,6 +4,11 @@
 }
 
 .stage-flow__stage {
+  --stage-flow-accent-color: var(
+    --nox-theme-accent-color,
+    var(--nox-tone-color)
+  );
+
   display: grid;
   inline-size: max-content;
   min-inline-size: var(--stage-flow-stage-min-inline-size);
@@ -33,7 +38,7 @@
 
 .stage-flow__stage[aria-current='page'] [data-widget='media-frame'] {
   border-width: 4px;
-  border-color: var(--nox-tone-color);
+  border-color: var(--stage-flow-accent-color);
   background:
     radial-gradient(
       circle at 50% 42%,
@@ -42,7 +47,7 @@
     ),
     var(--nox-tone-background);
   box-shadow:
-    0 0 0 1px var(--nox-tone-color),
+    0 0 0 1px var(--stage-flow-accent-color),
     0 0.35rem 0.75rem
       color-mix(in srgb, var(--nox-tone-shadow) 16%, transparent);
 }
@@ -56,9 +61,9 @@
 
 .stage-flow__stage[aria-current='page']:focus-visible
   [data-widget='media-frame'] {
-  border-color: var(--nox-tone-color);
+  border-color: var(--stage-flow-accent-color);
   box-shadow:
-    0 0 0 1px var(--nox-tone-color),
+    0 0 0 1px var(--stage-flow-accent-color),
     0 0 0 6px color-mix(in srgb, var(--nox-tone-focus-ring) 18%, transparent),
     0 0.5rem 1rem color-mix(in srgb, var(--nox-tone-shadow) 18%, transparent);
 }
@@ -83,7 +88,8 @@
     [data-widget='media-frame'] {
     box-shadow:
       0 0 0 1px var(--nox-border),
-      0 0 0 5px color-mix(in srgb, var(--nox-tone-color) 16%, transparent),
+      0 0 0 5px
+        color-mix(in srgb, var(--stage-flow-accent-color) 16%, transparent),
       0 0.5rem 1rem color-mix(in srgb, var(--nox-tone-shadow) 18%, transparent);
   }
 }

package/src/styles/base.css

@@ -167,6 +167,19 @@ p {
   gap: 0;
 }
 
+:root[data-appearance='halloween'] .site-shell {
+  isolation: isolate;
+}
+
+:root[data-appearance='halloween'] .site-viewport {
+  background: transparent;
+}
+
+:root[data-appearance='halloween'] .site-main__content {
+  background: var(--nox-page-background);
+  border-radius: var(--nox-radius-lg);
+}
+
 @media (width < 48rem) {
   .site-viewport {
     --site-content-gap: var(--nox-space-4);

package/src/styles/interaction.css

@@ -16,7 +16,10 @@
     var(--nox-link-active) 8%,
     var(--nox-surface)
   );
-  --nox-interaction-accent-color: var(--nox-link-active);
+  --nox-interaction-accent-color: var(
+    --nox-theme-accent-color,
+    var(--nox-link-active)
+  );
 
   position: relative;
 }

package/src/styles/style.css

@@ -1,6 +1,7 @@
 @layer settings, base, composition, primitives, components, patterns, surfaces, states, responsive;
 
 @import './tokens.css' layer(settings);
+@import '../theme/halloween.css' layer(settings);
 @import './base.css' layer(base);
 @import './interaction.css' layer(states);
 
@@ -46,6 +47,8 @@
 @import '../components/forms/Textarea/Textarea.css' layer(components);
 @import '../components/feedback/Tooltip/Tooltip.css' layer(components);
 @import '../components/feedback/Spinner/Spinner.css' layer(components);
+@import '../components/feedback/SeasonalDecorations/SeasonalDecorations.css'
+  layer(components);
 @import '../components/icons/CurrencyIcon.css' layer(components);
 @import '../components/icons/CircleSymbolIcon.css' layer(components);
 @import '../components/media/CanvasFrame/CanvasFrame.css' layer(components);

package/src/theme/contracts.ts

@@ -2,3 +2,21 @@ export type Tone =
   'neutral' | 'primary' | 'info' | 'success' | 'warning' | 'danger';
 
 export type ColorTheme = 'light' | 'dark';
+
+export type SeasonalAppearance = 'halloween';
+
+export type ThemeAppearance = ColorTheme | SeasonalAppearance;
+
+export type AnnualThemePeriod = {
+  /** Inclusive local date, with months numbered from 1 to 12. */
+  start: { month: number; day: number };
+  /** Exclusive local date, possibly in the following year. */
+  end: { month: number; day: number };
+};
+
+export type SeasonalThemeConfig = {
+  id: string;
+  appearance: SeasonalAppearance;
+  decorations?: 'static' | 'animated';
+  annualPeriod?: AnnualThemePeriod;
+};

package/src/theme/halloween.css

@@ -0,0 +1,20 @@
+:root[data-appearance='halloween'] {
+  color-scheme: dark;
+
+  --nox-source-tone-neutral: #b6aaa0;
+  --nox-source-tone-primary: #ff9a3c;
+  --nox-content-link-color: #ffb66c;
+  --nox-theme-page-base: #12100f;
+  --nox-theme-surface-base: #201b18;
+  --nox-theme-text-base: #f3eee8;
+  --nox-theme-text-disabled-base: #776b63;
+  --nox-theme-border-base: #342820;
+  --nox-theme-inverse-base: #12100f;
+  --nox-theme-shadow-base: #090706;
+
+  --nox-seasonal-header-background: #211512;
+  --nox-seasonal-blood: #a52330;
+  --nox-seasonal-border-size: 3px;
+  --nox-seasonal-web: #d1bfa9;
+  --nox-theme-accent-color: var(--nox-seasonal-blood);
+}

package/src/theme/runtime.ts

@@ -0,0 +1,13 @@
+import type { ThemeAppearance } from './contracts';
+
+export type ThemeRuntime = {
+  next: () => ThemeAppearance;
+  cycle: () => void;
+  destroy: () => void;
+};
+
+declare global {
+  interface Window {
+    __astronoxTheme?: ThemeRuntime;
+  }
+}