core

@pageel/theme-core

Official Astro Integration Engine for Pageel Themes with W3C DTCG Token Pipeline and CSS Cascade Layer Support.

---

✨ Features

• 🎨 W3C DTCG Token Pipeline: First-class support for Design Tokens Community Group specification ($value, $type, token aliases like {color.primitive.slate.50}).
• 🔄 Immutable Token Resolver: Automatic deep merging of theme baseline tokens and user project overrides.
• 🥞 CSS Cascade Layers (@layer): Built-in 6-tier layer architecture (pageel.tokens, pageel.components, pageel.overrides) eliminating specificity conflicts.
• 🌓 Zero-FOUC Dark Mode: Automatic injection of inline theme script supporting localStorage and prefers-color-scheme.
• 🛡️ Theme Contract Validation: Pre-build validation of required semantic tokens (--color-bg, --color-fg, --color-accent, etc.).

---

📦 Installation

pnpm add @pageel/theme-core
# or
npm install @pageel/theme-core

---

🚀 Quick Start

Add the integration to your astro.config.mjs:

import { defineConfig } from 'astro/config';
import createPageelTheme from '@pageel/theme-core';

export default defineConfig({
  integrations: [
    createPageelTheme({
      theme: '@pageel/theme-starter',
      features: {
        darkMode: true,
        cssLayers: true,
        validation: true,
      },
    }),
  ],
});

---

⚙️ Configuration Options

export interface PageelThemeOptions {
  /**
   * Theme package name or relative path to theme directory
   * @default '@pageel/theme-starter'
   */
  theme?: string;

  /**
   * Path to user custom tokens override JSON
   * @default './tokens.json' (if present)
   */
  tokens?: string;

  /**
   * Feature flags
   */
  features?: {
    /** Enable zero-FOUC dark mode script injection (default: true) */
    darkMode?: boolean;
    /** Wrap tokens in @layer pageel.tokens (default: true) */
    cssLayers?: boolean;
    /** Validate Theme Contract at build time (default: true) */
    validation?: boolean;
  };

  /**
   * Additional custom CSS files to import
   */
  customCss?: string[];
}

---

🧪 Development & Testing

# Typecheck TypeScript packages
pnpm lint:ts

# Validate Astro templates
pnpm lint:astro

# Run full Vitest unit test suite
pnpm test

# Run entire verification gate
pnpm check

---

📄 License

MIT © Pageel Workspace