> For the complete documentation index, see [llms.txt](https://suigar.gitbook.io/suigar-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suigar.gitbook.io/suigar-docs/playing-on-suigar/event-periods.md). # Event periods This document captures the current implementation for Suigar's seasonal "event periods". It should help future contributors extend or adjust the system quickly. ## Supported Event Windows Each event has an activation window. Most windows are fixed month/day ranges (inclusive) and can wrap the year (e.g. Christmas). Easter is computed relative to Easter Sunday so it tracks the real holiday period. When the current date sits inside a window, that event becomes active unless a developer override is in place. | Event ID | Name | Date Range (Month/Day) | Notes | | --------------- | -------------------- | ------------------------ | --------------------------------------------------------- | | `saint-patrick` | Saint Patrick's Week | Mar 14 – Mar 20 | shamrock/emerald palette | | `valentines` | Valentine's Season | Feb 08 – Feb 16 | rosy reds & blush | | `easter` | Easter Celebration | Easter Sunday -7d to +3d | pastel spring palette | | `summer` | Summer Splash | Jul 01 – Aug 09 | tropical sunset vibe | | `halloween` | Halloween Spree | Oct 20 – Nov 02 | gothic purple + pumpkin orange (light theme mirrors dark) | | `christmas` | Christmas & New Year | Dec 01 – Jan 02 | evergreen & holly red | | `default` | Standard Suigar | (fallback) | non-event styling | The windows are defined in `frontend/src/configs/event-theme.ts` (Easter uses a dedicated runtime calculation). ## Core Building Blocks ### 1. Event configuration (`frontend/src/configs/event-theme.ts`) Every event entry now delivers a full bundle of presentation data: * **Assets** – duplicated logos and icons live under `frontend/src/assets/events//` and are wired into the config. Swap the files in place when real artwork is ready. * **Suifren defaults** – both Bullshark and Capy variants provide complete attribute sets (color, skin, expression, etc.) plus optional curated accessories pulled from `@suigar/suifrens-display-system`. Components can override pieces (for example to swap the expression) while staying on-brand. * **Metadata** – human readable name, description, and the calendar window that activates the event automatically. ```ts export const eventThemes: EventThemeConfig[] = [ { id: "summer", suifren: { bullshark: { attributes: buildBullshark({ mainColor: "FF9519", expression: "cool" }), accessories: pickAccessories("baseball cap", "lifeguard"), }, capy: { attributes: buildCapy({ mainColor: "FF9519", expression: "cool", earShape: "wild", }), accessories: pickAccessories("baseball cap", "lifeguard"), }, }, assets: { /* logo/icon overrides */ }, // …dates & copy omitted }, ]; ``` ### 2. Runtime provider (`frontend/src/providers/EventThemeProvider.tsx`) * Determines the active event from today’s date and pushes `data-event=""` onto the `` element. * Dev toggles: query string (`?event=christmas`), localStorage override, and a Ctrl/Cmd + E cycling hotkey. In dev builds a floating selector appears bottom-right for instant previewing. * The provider sits just under the global `ThemeProvider` in `frontend/src/main.tsx` so both the shadcn theme and the event attribute update together. ### 3. Suifren helper hook (`frontend/src/hooks/use-event-suifren.ts`) The hook merges per-event defaults with per-usage tweaks in a type-safe way: ```ts const { attributes, accessories } = useEventSuiFrenAppearance({ variant: "capy", attributes: { expression: "bigSmile" }, }); ``` * `variant` defaults to `'bullshark'`, so you can omit it for shark renders. * Accessories from the event override duplicate types, but you can still supply custom pieces (they’ll merge by accessory type). ### 4. Event-aware components Current components that honour the active event: | Component | Behaviour | | ------------------------------------------- | ---------------------------------------------------------------- | | `frontend/src/components/side-menu.tsx` | Switches logos/icons & SuiFren header art based on event assets. | | `frontend/src/components/login-modal.tsx` | Uses event-specific full logo. | | `frontend/src/components/welcome-modal.tsx` | Same as login modal. | | `frontend/src/components/CasinoFooter.tsx` | Swaps footer logo & background Suifren silhouettes. | | `frontend/src/pages/coinflip.tsx` | Hero Suifren picks season palette/accessories. | | `frontend/src/pages/range.tsx` | Uses seasonal attributes for moving Suifren. | | `frontend/src/pages/lootbox.tsx` | Seasonal hero Suifren near the rift. | | `frontend/src/pages/homepage.tsx` | Background Suifren near hero area tinted per event. | | `frontend/src/pages/roadmap.tsx` | Timeline Suifren characters follow event style. | All other `SuiFrenImage` usages remain default but can opt-in via the hook. ## Assets & Structure Event-specific files were cloned from the default assets. Replace them as needed: ``` frontend/src/assets/events/ ├── christmas/ │ ├── icon.svg │ ├── icon-light.svg │ ├── icon-rounded.svg │ ├── icon-rounded.png │ ├── logo-dark.svg │ ├── logo-full.png │ ├── logo-full.svg │ ├── logo-light.svg │ └── suifrens/ │ ├── capy-top.png │ ├── capy-top-surprised.png │ ├── side-bullshark.svg │ └── side-capy.svg └── … (same structure for the other events) ``` Only **placeholders** exist right now (duplicates of the default assets). Swap them with themed artwork. ### What to replace per event * `logo-*.svg/png`: app header, footer, modals, etc. * `icon*.svg/png`: favicon-like usages and collapsed menu icon. * `suifrens/`: bespoke character imagery shown in side menu/footer. ## Styling Integration * `global.css` now contains event-specific palettes inside the same `@layer base`. Light and dark tokens update when `data-event` changes, while Halloween intentionally shares the dark palette for both themes. * Because overrides live in CSS custom properties, every shadcn component (and any Tailwind token that references them) reacts automatically. * If you need truly bespoke styling, add selectors such as `[data-event='easter'] .my-class { … }` – the provider keeps the attribute in sync everywhere. ## Dev Workflow 1. Provide event assets in `frontend/src/assets/events//` (overwrite the placeholders). 2. Adjust the `eventThemes` entry (colors, accessories) for special behaviour. 3. Use the dev selector panel (or the `?event=christmas` URL query) to preview. 4. Update component-level logic if more areas need seasonal treatment. ## Follow-up Ideas / TODOs * Expand the per-event palettes into Tailwind color tokens if utilities need direct access (everything currently flows through CSS vars). * Consider storing event windows in the backend for marketing-controlled launches. * Build a simple runtime check that warns if an event is missing an asset or a `bullshark/capy` configuration. ## Quick Reference * Configuration: `frontend/src/configs/event-theme.ts` * Provider: `frontend/src/providers/EventThemeProvider.tsx` * SuiFren helper: `frontend/src/hooks/use-event-suifren.ts` * Global palettes: `frontend/src/css/global.css` (search for `data-event` blocks) * Asset folders: `frontend/src/assets/events//` * Dev override: query `?event=`, localStorage (`suigar.event.override`), hotkey Ctrl/Cmd + E, or the in-app dev panel * Components already wired: side menu, footer, login modal, welcome modal, homepage hero, coinflip, range, lootbox, roadmap ## Asset & Deliverable Checklist For each event (`saint-patrick`, `valentines`, `easter`, `summer`, `halloween`, `christmas`): * `logo-light.svg`, `logo-dark.svg` * `logo-full.svg`, `logo-full.png` * `icon.svg`, `icon-light.svg` * `icon-rounded.svg`, `icon-rounded.png` * SuiFren imagery under `suifrens/` (`capy-top.png`, `capy-top-surprised.png`, `side-capy.svg`, `side-bullshark.svg`) When you swap in final artwork the provider and palettes are already wired, so just replace the placeholder files. Keep this file updated whenever additional components adopt the event theming system.