# theme-kit

> Astro theme management skill. Theme-Swappable architecture with semantic tokens, dark mode, and design system integration.

- Author: Tien Le
- Repository: pageel/pageel-theme-kit
- Version: 20260126110641
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/pageel/pageel-theme-kit
- Web: https://mule.run/skillshub/@@pageel/pageel-theme-kit~theme-kit:20260126110641

---

---
name: theme-kit
description: Astro theme management skill. Theme-Swappable architecture with semantic tokens, dark mode, and design system integration.
---

# theme-kit

A complete theme management skill for Astro projects. Includes theme validation, design system generation, and theme swapping capabilities.

## Features

- **Theme-Swappable Architecture**: Replace `src/theme/` folder to change theme
- **Semantic Tokens**: CSS variables for consistent styling
- **Light/Dark Mode**: Built-in theme toggle with cookie persistence
- **Design System Integration**: Generate design systems using ui-ux-pro-max (if available)
- **Theme Validation**: Verify theme compliance with standard structure

---

## Commands

### Validate Theme Structure

Check if a theme complies with the Theme-Swappable Standard:

```bash
python3 scripts/theme-validator.py /path/to/theme
```

**Output:**

- ✅ COMPLIANT: Theme is ready for use
- ❌ NON-COMPLIANT: Lists missing files/tokens

### Generate Design System (Requires ui-ux-pro-max)

If you have the `ui-ux-pro-max` skill installed, generate a design system:

```bash
python3 /path/to/ui-ux-pro-max/scripts/search.py "luxury spa wellness" \
        --design-system \
        --persist \
        --project-name "spa-theme" \
        --output-dir "/path/to/theme/"
```

This creates `design-system/MASTER.md` with colors, typography, and effects.

---

## Theme Structure Contract

Every theme must follow this structure:

```
src/
├── theme.config.ts          # Project theme settings
├── theme-manager.ts         # (Optional) Logic layer
└── theme/                   # 🔄 SWAP THIS FOLDER
    ├── config.ts            # Theme metadata
    ├── styles/
    │   ├── global.css       # Entry point
    │   └── theme/
    │       ├── base.css     # Spacing, radius
    │       ├── semantic.css # Token aliases
    │       ├── light.css    # Light mode values
    │       └── dark.css     # Dark mode values
    ├── components/
    │   └── layout/          # ThemeToggle, etc.
    └── layouts/
        └── BaseLayout.astro
```

### Required Semantic Tokens

All themes MUST define these CSS variables:

| Token               | Description           |
| ------------------- | --------------------- |
| `--color-bg`        | Background color      |
| `--color-fg`        | Text color            |
| `--color-muted`     | Secondary text        |
| `--color-accent`    | Brand/CTA color       |
| `--color-on-accent` | Text on accent        |
| `--color-border`    | Border color          |
| `--color-surface`   | Card/modal background |

---

## Quick Start

### Create New Project from Starter

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

### Switch Theme in Existing Project

1. Backup current theme: `mv src/theme src/theme-backup`
2. Copy new theme: `cp -r path/to/new-theme/src/theme src/theme`
3. Update `src/theme.config.ts` with new theme name
4. Test: `npm run dev`
5. Cleanup: `rm -rf src/theme-backup`

---

## Files Included

| File                         | Purpose                     |
| ---------------------------- | --------------------------- |
| `SKILL.md`                   | This documentation          |
| `scripts/theme-validator.py` | Theme validation script     |
| `THEME_CONTRACT.md`          | Full contract specification |

---

## Related

- [THEME_CONTRACT.md](../../THEME_CONTRACT.md) - Full contract documentation
- [themes/starter/](../../themes/starter/) - Starter theme template

---

_Version: 1.0.0 | License: MIT_