Seasons

Seasons is a season-aware neobrutalist blog theme built with Astro and Tailwind CSS that automatically switches its color palette based on the visitor's local date. It is a modified version of astro-palette by Josh Ruggles, reworked by Nico Miguelino and released under AGPL-3.0-or-later.

What is Seasons?

Seasons is an Astro blog theme that ships as a GitHub template repository you generate a project from with npm create astro@latest -- my-site --template nicomiguelino/astro-seasons. It produces a statically built blog with a home page, blog index, individual posts, tag archives, an experience page, a projects page, a colors page, an RSS feed and a 404 page. Palettes change with the calendar rather than by rebuild.

What makes Seasons stand out?

• Date-driven seasonal palettes — five palette families: autumn-* runs Sept 22 to Dec 21, winter-* Dec 22 to Mar 19, spring-* Mar 20 to Jun 20, summer-* Jun 21 to Sept 21, plus neon-* available only from the theme picker.
• Light and dark per season — the mode comes from the theme toggle, falls back to prefers-color-scheme, and stores only site-mode in localStorage so a preference carries across seasons.
• No flash of wrong colors — initializePalette() sets data-palette on <html> from <head> and the body stays hidden until it is set.
• Seasonal ambient effects — FallingLeaves, FallingSnow and FallingPetals for autumn, winter and spring; summer instead gets HeatShimmer (an SVG displacement filter) and Sunlight (a pulsing glow), all gated by prefers-reduced-motion.
• Theme picker in the navbar — overrides the date with Automatic, any of the four seasons, or Neon, stored as site-theme.
• Fuse.js search — static-page and post search entries defined in src/lib/search.ts.
• Playwright testing — E2E and screenshot specs in src/tests/, with a separate astro preview server on port 4322 and pinned clocks and fixture content.
• Husky pre-commit hook — runs lint:check, format:check and check on commit.

Who is it for?

• Personal bloggers who want a distinctive neobrutalist site that changes look through the year without manual edits.
• Astro developers wanting a ready-made template with type checking, ESLint, Prettier and Playwright already wired up.
• GitHub Pages deployers who need base-path handling through withBase() from src/lib/paths.ts.

How does Seasons work?

Generate the project with the Astro CLI or clone the repo, then replace the placeholders in src/lib/site.ts (SITE_NAME, AUTHOR_NAME, SITE_URL, GITHUB_URL, SOURCE_URL). Run npm run dev for the server on port 4321, npm run build for a production build, and npm run test:e2e for Playwright. Posts are markdown files in src/content/blog/ with title, description, date and optional tags and draft frontmatter.

What can you do with Seasons?

• Preview a season: set document.documentElement.dataset.palette = 'autumn-dark' in the browser console to see any palette.
• Add a season: extend THEME_CHOICES, the picker options in ThemePicker.astro, palettes.css, PaletteFamily and the seasons config in PALETTE_CONFIG.
• Deploy under a sub-path: build with SITE_URL and BASE_PATH environment variables set for GitHub Pages project pages.

FAQ

Is Seasons free?

Yes. Seasons is licensed AGPL-3.0-or-later and is published as a public template repository. If you deploy a modified version as a website, AGPL section 13 requires you to offer users the corresponding source code, which is why SOURCE_URL in src/lib/site.ts exists.

Does the palette change require a rebuild?

No. The palette family is read from the visitor's local date on every page load, so a new season starts without rebuilding the site.

Can I turn off the falling effects?

Yes. Every seasonal effect only renders when the palette matches and when prefers-reduced-motion allows it.

Does the screenshot test fail on visual changes?

No. Screenshots are captured, not compared, so tests do not fail on visual changes; you review the images in git diff.