Skip to content
BranchesTags

Repository files navigation

Astro Theme Switcher

A production-ready, token-based themeable design system for Astro. Build beautiful websites with runtime theme switching, semantic design tokens, and a comprehensive component library. Perfect for developers and agencies who need a flexible, extensible theming solution.

✨ Features

  • 🎨 Token-Based Theme System - Semantic design tokens with runtime theme switching
  • 🌓 Light/Dark Mode - Separate mode toggle for each color theme
  • 🎭 Premium Themes - Aurora and Obsidian themes with custom typography
  • 🧩 Component Library - Production-ready, theme-aware UI components
  • 🚀 Astro - Lightning-fast static site generation
  • ⚛️ React - Interactive components (ThemeSwitcher, ModeToggle)
  • 🎨 Tailwind CSS v4 - Fully integrated with semantic tokens
  • 📝 MDX - Write JSX in your Markdown documents
  • 🎯 Astro Icons - Beautiful icon component library with Tabler icon set
  • 📖 Tailwind Typography - Beautiful typography styles for markdown content

🛠️ Tech Stack

Core Framework

  • Astro ^6.0.5 - The web framework for content-driven websites

Integrations

  • @astrojs/react ^5.0.0 - React integration for Astro
  • @astrojs/mdx ^5.0.1 - MDX support for writing JSX in Markdown
  • @astrojs/sitemap ^3.7.1 - Sitemap generation
  • astro-icon ^1.1.5 - Icon component library

Styling

  • tailwindcss ^4.1.18 - Utility-first CSS framework
  • @tailwindcss/vite ^4.1.18 - Tailwind CSS Vite plugin
  • @tailwindcss/typography ^0.5.19 - Typography plugin for beautiful markdown styling
  • sass ^1.97.2 - CSS preprocessor

UI & Animation

  • framer-motion ^12.24.7 - Production-ready motion library for React
  • react ^19.2.3 - UI library
  • react-dom ^19.2.3 - React DOM renderer

Icons

  • @iconify-json/tabler ^1.2.26 - Tabler icon set for astro-icon

📁 Project Structure

/
├── public/
│   └── favicon.svg
├── src/
│   ├── assets/          # Static assets (images, SVGs)
│   ├── components/      # Reusable Astro components
│   │   ├── CTA.astro           # Call-to-action section
│   │   ├── Features.astro      # Features showcase
│   │   ├── Footer.astro        # Site footer
│   │   ├── Header.astro        # Site header/navigation
│   │   ├── Hero.astro          # Hero section
│   │   ├── ScrollReveal.tsx    # Scroll animation component
│   │   └── SassExample.astro   # Sass usage example
│   ├── layouts/
│   │   └── Layout.astro        # Base page layout
│   ├── pages/          # Routes (file-based routing)
│   │   ├── index.astro         # Homepage
│   │   ├── about.astro         # About page
│   │   ├── contact.astro      # Contact page
│   │   ├── features.astro      # Features page
│   │   └── example.mdx         # MDX example page
│   └── styles/
│       ├── global.css          # Global styles & Tailwind imports
│       └── example.scss        # Sass example file
├── astro.config.mjs    # Astro configuration
├── tailwind.config.mjs # Tailwind configuration
└── package.json

🚀 Getting Started

Prerequisites

  • Node.js 22.12.0 or higher (required for Astro 6)
  • npm, pnpm, or yarn

Installation

  1. Clone the repository

    git clone https://github.com/jonnysmillie/astro-theme-switcher.git
cd astro-theme-switcher

  2. Install dependencies

    npm install

  3. Start the development server

    npm run dev

  4. Open your browser Navigate to http://localhost:4321

📜 Available Scripts

Command Action
npm install Installs dependencies
npm run dev Starts local dev server at localhost:4321
npm run build Build your production site to ./dist/
npm run preview Preview your build locally
npm run astro Run CLI commands like astro add, astro check

🎨 Styling

Tailwind CSS

This project uses Tailwind CSS v4 for styling. All components use Tailwind utility classes.

Global Styles:

  • Located in src/styles/global.css
  • Imports Tailwind CSS
  • Includes Tailwind Typography plugin for markdown styling

Configuration:

  • tailwind.config.mjs - Tailwind configuration with Typography plugin

Sass

Sass is installed and ready to use. You can use Sass in component <style> blocks:

<style lang="scss">
	$primary-color: #000;

	.my-component {
		color: $primary-color;
	}
</style>

See src/components/SassExample.astro for a complete example.

🎭 Components

ScrollReveal

A React component using Framer Motion for scroll-triggered animations:

import ScrollReveal from "./ScrollReveal.tsx";

<ScrollReveal client:load delay={0.2} scale={true}>
	<div>Your content here</div>
</ScrollReveal>;

Props:

  • delay - Animation delay in seconds (default: 0)
  • direction - Animation direction: "up" | "down" | "left" | "right" (default: "up")
  • distance - Distance to travel in pixels (default: 50)
  • scale - Enable scale animation (default: false)

Icons

Use Tabler icons with astro-icon:

---
import { Icon } from "astro-icon/components";
---

<Icon name="tabler:heart" class="w-6 h-6" />

Browse available icons at Tabler Icons.

📝 MDX Support

Write JSX in your Markdown documents. Create .mdx files in the src/pages directory:

---
import Layout from "../layouts/Layout.astro";
---

<Layout>
	# My MDX Page This is **markdown** with <Component /> support!
</Layout>

See src/pages/example.mdx for a complete example.

🎯 Pages

  • / - Homepage with hero, features, and CTA sections
  • /features - Features showcase page
  • /about - About page
  • /contact - Contact form page
  • /example - MDX example page demonstrating markdown features

🔧 Configuration

Astro Config (astro.config.mjs)

export default defineConfig({
	integrations: [
		react(), // React support
		icon(), // Astro Icons
		mdx(), // MDX support
	],
	vite: {
		plugins: [tailwindcss()],
	},
});

Tailwind Config (tailwind.config.mjs)

import typography from "@tailwindcss/typography";

export default {
	plugins: [typography],
};

📦 Key Dependencies

Core

  • Astro - Web framework
  • React - UI library for interactive components
  • Tailwind CSS - Utility-first CSS framework

Integrations

  • @astrojs/react - React integration
  • @astrojs/mdx - MDX support
  • @astrojs/sitemap - Sitemap generation
  • astro-icon - Icon component library

Styling

  • @tailwindcss/typography - Typography plugin
  • sass - CSS preprocessor

Animation

  • framer-motion - Motion library

Icons

  • @iconify-json/tabler - Tabler icon set

🎨 Theme System

Astro Theme Switcher includes a comprehensive token-based theme system:

  • Runtime Theme Switching - Change themes without page reload
  • Semantic Design Tokens - All colors, typography, spacing use semantic tokens
  • Light/Dark Mode - Separate mode toggle for each color theme
  • Multiple Color Themes - Blue, Green, Purple, Orange, plus premium Aurora and Obsidian
  • Framework-Agnostic Core - Theme system works independently of UI framework
  • Easy to Extend - Add new themes in minutes without touching components

See THEME_SYSTEM.md and src/themes/README.md for detailed documentation.

🎨 Design Features

  • Token-Based Theming - Semantic design tokens for consistent styling
  • Responsive Layout - Mobile-first approach
  • Smooth Animations - Scroll reveal effects with spring physics
  • Modern Typography - Beautiful text styling with Tailwind Typography
  • Component Library - Production-ready, theme-aware UI components

📚 Learn More

📄 License

MIT License. See LICENSE for full terms.

🙏 Credits

Built with:

Ready to build something amazing? Clone the repo and start creating beautiful, themeable websites!

About

A production-ready, token-based themeable design system for Astro. Build beautiful websites with runtime theme switching, semantic design tokens, and a comprehensive component library.

astro-theme-switcher.netlify.app/

Resources

Readme
MIT license
Activity

Stars

4 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

Packages

Contributors

Languages