Pageel Theme Kit

The ultimate swappable architecture for Astro. Built for speed, consistency, and AI-assisted design.

---

✨ Features

• 🔄 Theme-Swappable: One folder (src/theme/) to rule them all. Swap interfaces without touching content.
• 🎨 Semantic Design: Built-in tiered token system (Base → Semantic → Component).
• 🌓 Dark Mode Native: First-class support with cookie persistence and light/dark CSS tokens.
• 🤖 AI-Ready: Integrated with theme-kit skill for automated validation and design generation.
• 🏗️ Core Logic: Managed by @pageel/theme-core for robust reliability.

🚀 Quick Start

Option 1: Use CLI Tool (Recommended)

Note: This package is currently in Local Development mode.

1. Setup CLI:

   # Clone repo
   git clone https://github.com/pageel/pageel-theme-kit
   cd pageel-theme-kit/packages/cli
   
   # Build & Link
   npm install && npm run build
   npm link

2. Use in your project:

   # Go to your Astro project
   cd ../my-existing-astro-site
   
   # Run installer
   pageel-theme install

Option 2: Manual Clone

Spin up a new project in seconds:

npx degit pageel/pageel-theme-kit/themes/starter my-project
cd my-project && npm install && npm run dev

🧠 AI Agent Intelligence

This kit is designed for Agentic Coding. It includes built-in intelligence for AI agents to automate design and validation.

• theme-kit Skill: Our native skill that allows agents to validate theme compliance and manage swaps autonomously.
• ui-ux-pro-max Recommended Integration: Harness the power of 100+ design systems and UX rules. This kit is fully compatible with the ui-ux-pro-max design intelligence skill to help you generate professional style guides directly into your themes.

🛠 Usage

1. Installation

Clone the kit or use the starter template:

npx degit pageel/pageel-theme-kit/themes/starter my-theme
cd my-theme && npm install

2. Customizing Styles

Modify the CSS variables in src/theme/styles/theme/ to change your brand colors and tokens:

• light.css / dark.css: Base color palettes.
• semantic.css: Mapping base colors to functional roles (bg, fg, accent).

3. Validation

Ensure your theme follows the Theme-Swappable Standard:

# Using the theme-kit skill
python3 .agent/skills/theme-kit/scripts/theme-validator.py .

4. Switching Themes

To rotate a visual design, simply replace the contents of src/theme/ with another compliant theme folder.

🏗 Architecture

Keep your content stable, rotate your visual universe:

src/
├── theme/               # 🔄 SWAP THIS (UI/UX)
├── pages/               # ✅ STABLE (Routes)
├── content/             # ✅ STABLE (Data)
└── theme.config.ts      # ⚙️ SETTINGS

🛠 Included Tools

• Theme Validator: Ensure your theme meets the Pageel Contract. Path: .agent/skills/theme-kit/scripts/theme-validator.py.
• Design System Generator: Craft professional palettes via ui-ux-pro-max integration.

📦 Packages

Package	Purpose
@pageel/theme-core	ThemeManager logic & Validation engine
pageel-theme	Interactive CLI for installing themes
starter	The optimal blueprint for new themes

🤝 Contribution

We welcome community themes! Please see CONTRIBUTING.md for guidelines on creating submittable OSS themes.

---

Built with ❤️ by Pageel