@kilivi/payloadcms-theme-management 2.0.0 → 2.2.0

package/README.md

@@ -1,117 +1,98 @@
-# Theme Management Plugin for Payload CMS v3
+# @kilivi/payloadcms-theme-management
 
-A comprehensive theme management plugin for Payload CMS v3 that provides powerful theming capabilities with SSR support, preventing FOUC (Flash of Unstyled Content).
+Theme management for Payload CMS v3: 60+ presets, a live preview inside the admin, an accessibility audit, and theme CSS variables that are rendered server-side (SSR-ready) for your Next.js front-end. It is built so that a non-technical site owner can restyle a site from the Payload admin without breaking it.
 
-## 🎉 Version 1.0.2 - Production Ready!
+**Repository:** [github.com/vitakili/payload-plugins → packages/theme-management](https://github.com/vitakili/payload-plugins/tree/main/packages/theme-management) · [Changelog](./CHANGELOG.md) · [Issues](https://github.com/vitakili/payload-plugins/issues)
 
-- **✅ Standalone Global Support** - Create separate appearance settings as a global
-- **✅ Auto-Populate Light/Dark Colors** - Theme selection hook automatically fills color fields
-- **✅ Multi-Tenant Ready** - Full support for multi-tenant applications with isolated themes
-- **✅ Cache Invalidation** - Automatic cache invalidation after saving appearance settings
-- **✅ Live Theme Preview** - Real-time theme preview in admin panel at `/admin/theme-preview`
-- **✅ Professional Color Picker** - Enhanced color picker with react-colorful library
-- **✅ shadcn/ui Compatible** - Works with https://ui.shadcn.com/themes
-- **✅ TweakCN Compatible** - Works with https://tweakcn.com/editor/theme
+> **Package name:** the plugin is published as **`@kilivi/payloadcms-theme-management`**. Versions 1.x–2.1.x were also published under `@kilivi-dev/payloadcms-theme-management`, which is no longer updated. See [Migrating from `@kilivi-dev`](#migrating-from-kilivi-dev).
 
 ## Features
 
-- 🎨 **Multiple Theme Presets** - Cool, Brutal, Neon, Solar, and more
-- 🎯 **Auto-Populate Colors** - Theme selection automatically sets Light/Dark mode colors
-- 🌍 **Standalone Global** - Create separate appearance settings global (v0.6.0+)
-- 🖼️ **Live Theme Preview** - Real-time preview in admin panel (no configuration needed!)
-- 🎨 **Extended Themes** - OKLCH-based themes with full shadcn/ui token support
-- 🎨 **Custom Color Palette** - Full HSL color customization (19 semantic tokens)
-- 🔤 **Typography Control** - Google Fonts integration for headings, body, and code
-- 📐 **Border Radius Presets** - Sharp, Rounded, or Pill styles
-- 🌓 **Dark Mode Support** - Built-in light/dark/system mode toggle
-- 📊 **Chart Colors** - Data visualization color palette
-- 🚀 **SSR Theme Injection** - Zero FOUC with server-side rendering
-- ⚡ **Performance Optimized** - Critical CSS inlining, preload links
-- 🎯 **Type Safe** - Full TypeScript support
-- 🔧 **Highly Configurable** - Flexible plugin options
-- 👥 **Multi-Tenant Support** - Built-in multi-tenant capabilities
+- **Theme presets:** 60+ colour themes (including tweakcn and OKLCH styles) plus visual style presets that set effects, component styles, radius and typography.
+- **"Keep my" locks:** lock *Colours*, *Fonts* or *Style* so that picking a theme, applying a style or generating a palette leaves those parts untouched.
+- **One-step undo:** every bulk change (theme, style, generated palette) can be undone from an *Applied: … · Undo* bar.
+- **One live preview:** colours, fonts and component styles in a single site mock-up with device widths and light/dark mode. On wide admin screens it stays in view in a column on the right while you edit.
+- **Palette generator:** a full light and dark palette from one brand colour or an uploaded logo.
+- **WCAG audit:** a live contrast check of the palette in both modes, with a one-click *Fix* for each failing pair. Paired colour fields (for example `primary` and `primaryForeground`) also show their contrast right in the field.
+- **Export and import:** W3C design tokens (JSON), Tailwind v4 `@theme` and Tailwind v3 config. Custom presets can be imported as JSON and appear in the theme picker straight away.
+- **Front-end rendering:** SSR theme injection (`ServerThemeInjector`), `<meta name="theme-color">`, cache revalidation and Payload Live Preview.
+- **Visitor components:** `ColorModeToggle` (light/dark/auto) and `ThemeSwitcher`.
+- **Native to Payload:** uses Payload's theme tokens, so it works in the dark admin, has keyboard-accessible pickers and respects `prefers-reduced-motion`. It ships with English and Czech admin translations, and you can add more.
 
 ## Installation
 
 ```bash
 pnpm add @kilivi/payloadcms-theme-management
 # or
-npm install @kilivi/payloadcms-theme-management
+npm i @kilivi/payloadcms-theme-management
 # or
 yarn add @kilivi/payloadcms-theme-management
 ```
 
-## Quick Start
+**Peer dependencies:**
 
-### 1. Add Plugin to Payload Config
+| Package | Versions |
+| --- | --- |
+| `payload`, `@payloadcms/ui` | `^3` |
+| `next` | `14` / `15` / `16` |
+| `react` | `18.3+` or `19` |
+| `lucide-react` | `>=0.400` |
 
-#### Option A: Add as Tab to Existing Collection (Default)
+## Quick start
 
-```typescript
+### 1) Register the plugin
+
+#### A) As a tab in an existing collection (default)
+
+```ts
 import { themeManagementPlugin } from '@kilivi/payloadcms-theme-management'
 import { buildConfig } from 'payload'
 
 export default buildConfig({
-  // ... other config
-
   collections: [
     {
       slug: 'site-settings',
-      fields: [
-        {
-          name: 'siteName',
-          type: 'text',
-        },
-        // Theme configuration will be injected here as a tab inside this collection
-      ],
+      fields: [{ name: 'siteName', type: 'text' }],
     },
   ],
-
   plugins: [
     themeManagementPlugin({
-      enabled: true,
       targetCollection: 'site-settings',
       defaultTheme: 'cool',
-      includeColorModeToggle: true,
-      enableLogging: true,
+      livePreview: true,
     }),
   ],
 })
 ```
 
-> **Note:** Option A injects an **Appearance Settings** tab into the specified collection (`targetCollection`). If you prefer a separate global (standalone settings), use **Option B** below and set `useStandaloneCollection: true` in the plugin options.
-
-#### Option B: Create Standalone Global (Separate Settings)
+#### B) As a standalone appearance global
 
-```typescript
+```ts
 import { themeManagementPlugin } from '@kilivi/payloadcms-theme-management'
 import { buildConfig } from 'payload'
 
 export default buildConfig({
-  // ... other config
-
   plugins: [
     themeManagementPlugin({
-      enabled: true,
-      useStandaloneCollection: true, // Creates a separate global
-      standaloneCollectionSlug: 'appearance-settings', // Optional: custom slug
-      standaloneCollectionLabel: 'Appearance Settings', // Optional: custom label
+      useStandaloneCollection: true,
+      standaloneCollectionSlug: 'appearance-settings',
+      standaloneCollectionLabel: 'Appearance Settings',
       defaultTheme: 'cool',
-      includeColorModeToggle: true,
-      enableLogging: true,
+      livePreview: true,
     }),
   ],
 })
 ```
 
-### 2. Add Server Theme Injection (Next.js)
+After adding the plugin, regenerate the admin import map:
 
-**⚠️ IMPORTANT:** Import from `/server` entry point!
+```bash
+pnpm payload generate:importmap
+```
 
-#### If Using Default (Tab in existing collection):
+### 2) Inject the theme in your Next.js layout
 
 ```tsx
-// app/layout.tsx
 import { ServerThemeInjector } from '@kilivi/payloadcms-theme-management/server'
 import configPromise from '@payload-config'
 import { getPayload } from 'payload'
@@ -119,15 +100,14 @@ import { getPayload } from 'payload'
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
   const payload = await getPayload({ config: configPromise })
 
-  const { docs } = await payload.find({
-    collection: 'site-settings', // Your target collection
-    limit: 1,
+  const appearance = await payload.findGlobal({
+    slug: 'appearance-settings',
   })
 
   return (
     <html lang="en">
       <head>
-        <ServerThemeInjector themeConfiguration={docs[0]?.themeConfiguration} />
+        <ServerThemeInjector themeConfiguration={appearance?.themeConfiguration} />
       </head>
       <body>{children}</body>
     </html>
@@ -135,889 +115,410 @@ export default async function RootLayout({ children }: { children: React.ReactNo
 }
 ```
 
-#### If Using Standalone Global:
+That is all an app needs. The fonts the editor picks are served from **your own
+domain** by the plugin's `/api/theme-fonts/*` endpoints (fetched and cached on the
+server), so visitors' browsers never contact Google (GDPR-friendly), with no setup.
 
-```tsx
-// app/layout.tsx
-import { ServerThemeInjector } from '@kilivi/payloadcms-theme-management/server'
-import configPromise from '@payload-config'
-import { getPayload } from 'payload'
+### 3) Optional: fonts via `next/font` (Next.js best practice)
 
-export default async function RootLayout({ children }: { children: React.ReactNode }) {
-  const payload = await getPayload({ config: configPromise })
+For build-time self-hosting with metric-matched fallbacks (no layout shift), add
+one import. Every catalog font is declared with `preload: false`, so a page only
+downloads the face it actually uses:
 
-  // Fetch from standalone global
-  const appearanceSettings = await payload.findGlobal({
-    slug: 'appearance-settings', // Your standalone global slug
-  })
+```tsx
+import { themeFontVariables } from '@kilivi/payloadcms-theme-management/next-fonts'
 
-  return (
-    <html lang="en">
-      <head>
-        <ServerThemeInjector themeConfiguration={appearanceSettings?.themeConfiguration} />
-      </head>
-      <body>{children}</body>
-    </html>
-  )
-}
+<html lang="en" className={themeFontVariables}>
+  <head>
+    <ServerThemeInjector themeConfiguration={appearance?.themeConfiguration} fontLoading="none" />
+  </head>
 ```
 
-#### Cache Optimization with Next.js (Out of the Box)
+If your Next.js setup does not compile packages from `node_modules`, add
+`'@kilivi/payloadcms-theme-management'` to `transpilePackages` in `next.config`.
+Pass `fontLoading="none"` to `ThemeLivePreviewSync` as well if you use it.
 
-When using standalone global, the plugin automatically invalidates cache after saving appearance settings using the tag `global_appearance-settings` (or `global_{your-slug}` if you use a custom slug).
+`fontLoading` options: `'self-hosted'` (default), `'google'` (Google Fonts CDN),
+`'none'` (you load the faces, e.g. with `next/font`).
 
-You can optimize your theme fetching by using the built-in server helper:
+## The Appearance Settings tab
 
-```tsx
-// app/layout.tsx
-import {
-  createCachedThemeFetcher,
-  ServerThemeInjector,
-} from '@kilivi/payloadcms-theme-management/server'
-import configPromise from '@payload-config'
-import { getPayload } from 'payload'
+The tab is ordered as a **presets first, fine-tuning second** workflow:
 
-const getCachedTheme = createCachedThemeFetcher({
-  globalSlug: 'appearance-settings',
-  revalidate: 3600,
-  loadAppearanceSettings: async () => {
-    const payload = await getPayload({ config: configPromise })
-    return payload.findGlobal({
-      slug: 'appearance-settings',
-    })
-  },
-})
+1. **Theme selection:**
+   - *Keep my: Colours · Fonts · Style* locks
+   - the palette generator
+   - the collapsible theme preset list
+2. **Live preview:** with Payload's native Live Preview configured (`livePreview` option), the real site is the preview: the tab shows an *Open Live Preview* button instead of a mock, and nothing while the panel is open, so the fields get the full width. Without it, one mock preview covers colours, fonts and component styles. Once the settings group is at least 960 px wide (a container query, not the viewport width), it moves into a sticky right-hand column that stays visible while you edit anything below it.
+3. **Style preset:** 17 complete looks (Swiss, Editorial, Luxury, Art Deco, Tech, Poster, Brutalism, Retro, Glass …). Each sets fonts, text size, heading weight and tracking, radius, spacing, effects and every component style — but never colours. Combine any style with any colour theme.
+4. **Typography:** body and heading font (30 curated Google fonts with Czech diacritics, grouped by category), base size, line height, heading weight and heading letter spacing.
+5. **Border radius and spacing scale.**
+6. **Fine-tuning sections:** these are collapsed by default.
+   - Visual effects
+   - Component styles
+   - Colour mode (all light and dark tokens, the WCAG audit and export)
+   - Custom theme presets (JSON import, for developers)
+   - Advanced (animation level, custom CSS)
 
-export default async function RootLayout({ children }: { children: React.ReactNode }) {
-  const themeConfiguration = await getCachedTheme()
+The generated CSS applies the chosen fonts to `body` and headings with
+zero-specificity `:where()` rules — only once the editor has picked typography,
+so untouched sites render as before and your own CSS always wins.
 
-  return (
-    <html lang="en">
-      <head>
-        <ServerThemeInjector themeConfiguration={themeConfiguration} />
-      </head>
-      <body>{children}</body>
-    </html>
-  )
-}
-```
+### Locks and undo
 
-**Benefits:**
+Each bulk action honours the locks:
 
-- ⚡ Theme settings are cached and reused across requests
-- 🔄 Cache automatically invalidates when you save appearance settings in admin
-- 🚀 Reduces database queries and improves performance
+| Action | Colours | Fonts | Style (effects, components, radius) |
+| --- | --- | --- | --- |
+| Pick a theme preset | writes colours | pins the current preset font instead of switching it | writes the theme's visual effects |
+| Pick a style preset | never | writes the style's typography | writes effects, components, radius, motion and spacing |
+| Generate a palette | writes colours (disabled while locked) | never | never |
 
-**Cache Tag Format:**
+- Locks last for the current editing session. They reset on reload and nothing extra is stored in your documents.
+- After each bulk action an *Applied: … · Undo* bar appears for 10 seconds. It pauses while you hover it or it has focus.
+- Undo restores exactly the fields that the action changed.
 
-- Default: `global_appearance-settings`
-- Custom slug: `global_{standaloneCollectionSlug}`
+## Live Preview
 
-#### Injected Revalidation Route
+Payload's Live Preview points at your client pages by slug:
 
-The plugin now injects a Payload endpoint (default: `POST /api/theme/revalidate`) that triggers the same tag/path invalidation logic used by live preview saves.
+- the `home` slug resolves to `/`
+- any other slug resolves to `/{slug}`
+- a tenant query is appended when one is available
 
 ```ts
 themeManagementPlugin({
-  useStandaloneCollection: true,
-  cacheRevalidation: {
-    routePath: '/theme/revalidate',
-    secret: process.env.THEME_REVALIDATE_SECRET,
-    tags: ['tenant:default'],
-    paths: ['/'],
-  },
+  livePreview: true,
 })
 ```
 
-Set `cacheRevalidation.injectRoute` to `false` if you want to keep only automatic hook-based invalidation.
-
-> **Note:** The cache invalidation hook is only available for standalone global mode. When using the tab mode (default), implement your own caching strategy based on your collection structure.
-
-### 3. Use Theme Variables in Your CSS
-
-The plugin injects CSS custom properties you can use:
-
-```css
-.my-component {
-  background-color: hsl(var(--background));
-  color: hsl(var(--foreground));
-  border-radius: var(--radius);
-  font-family: var(--font-body);
-}
-```
-
-Or with Tailwind CSS:
-
-```tsx
-<div className="bg-primary text-primary-foreground rounded-lg">Themed Content</div>
-```
-
-## Plugin Configuration Options
-
-| Option                      | Type                                  | Default                 | Description                                                          |
-| --------------------------- | ------------------------------------- | ----------------------- | -------------------------------------------------------------------- |
-| `enabled`                   | `boolean`                             | `true`                  | Enable/disable the plugin                                            |
-| `targetCollection`          | `string`                              | `'site-settings'`       | Collection slug to add theme field to (when not using standalone)    |
-| `useStandaloneCollection`   | `boolean`                             | `false`                 | Create a separate global instead of adding as a tab                  |
-| `standaloneCollectionSlug`  | `string`                              | `'appearance-settings'` | Slug for the standalone global                                       |
-| `standaloneCollectionLabel` | `string \| Record<string, string>`    | `'Appearance Settings'` | Label for the standalone global (supports i18n)                      |
-| `themePresets`              | `ThemePreset[]`                       | Built-in presets        | Custom theme presets                                                 |
-| `defaultTheme`              | `string`                              | `'cool'`                | Default theme preset name                                            |
-| `includeColorModeToggle`    | `boolean`                             | `true`                  | Show light/dark mode toggle                                          |
-| `includeCustomCSS`          | `boolean`                             | `true`                  | Allow custom CSS injection                                           |
-| `includeBrandIdentity`      | `boolean`                             | `false`                 | Show brand identity fields                                           |
-| `enableAdvancedFeatures`    | `boolean`                             | `true`                  | Enable advanced customization                                        |
-| `enableLogging`             | `boolean`                             | `false`                 | Log plugin actions to console (includes cache invalidation logs)     |
-| `livePreview`               | `boolean \| LivePreviewOptions`       | `true`                  | Enable/administer live preview URL resolution (`home` → fallback)    |
-| `cacheRevalidation`         | `boolean \| CacheRevalidationOptions` | `standalone: true`      | Configure injected route + tags/paths for Next.js cache invalidation |
-
-**Cache Invalidation Note:** In standalone mode, the plugin revalidates `global_{standaloneCollectionSlug}` automatically and injects `POST /api/theme/revalidate` by default. Pair it with `createCachedThemeFetcher` from `@kilivi/payloadcms-theme-management/server` for a zero-boilerplate setup.
-
-## Available Theme Presets
-
-- **Cool** - Professional blue theme
-- **Brutal** - High contrast, bold design
-- **Neon** - Vibrant, energetic colors
-- **Solar** - Warm, golden tones
-- **Dealership** - Automotive-inspired
-- **Real Estate** - Professional property theme (+ Gold, Neutral variants)
-
-## Live Theme Preview
-
-The plugin automatically adds a **Live Preview** page to your admin panel at `/admin/theme-preview`.
-
-### Features:
-
-- ✅ **Zero Configuration** - Works automatically when plugin is installed
-- ✅ **Real-time Updates** - See changes instantly as you edit theme settings
-- ✅ **Light/Dark Toggle** - Preview both modes side-by-side
-- ✅ **Component Showcase** - View cards, buttons, inputs, badges, and more
-- ✅ **Professional UI** - Clean, modern preview interface
-
-### How to Access:
-
-1. Install the plugin (see Quick Start above)
-2. Navigate to `/admin/theme-preview` in your Payload admin panel
-3. Open theme settings in another tab and see changes update live!
-
-The preview automatically watches your `themeConfiguration` field and displays real-time updates without any additional setup.
-
-## Translations / i18n
-
-Extend or override translations at runtime with `registerTranslations`. The plugin merges your translations with English defaults, so missing keys fall back to English. See `docs/TRANSLATIONS.md` for details and examples.
-
-## API Reference
+### Advanced setup (with the injected endpoint)
 
-### Main Entry Point
-
-Import from `@kilivi/payloadcms-theme-management` for client-safe code:
-
-```typescript
-// Plugin
-// Client Components
-
-// Utilities
-import {
-  fetchThemeConfiguration,
-  generateThemeColorsCss,
-  generateThemeCSS,
-  getThemeStyles,
-  resolveThemeConfiguration,
-  themeManagementPlugin,
-  ThemeProvider,
-} from '@kilivi/payloadcms-theme-management'
-// Types
-import type {
-  ThemeDefaults,
-  ThemeManagementPluginOptions,
-  ThemePreset,
-} from '@kilivi/payloadcms-theme-management'
+```ts
+themeManagementPlugin({
+  livePreview: {
+    enabled: true,
+    injectRoute: true,
+    routePath: '/theme/preview',
+    pageCollection: 'pages',
+    pageSlug: 'home',
+    fallbackToFirstPage: true,
+    tenantField: 'tenant',
+    tenantQueryParam: 'tenant',
+    breakpoints: [
+      { name: 'tablet', label: 'Tablet', width: 1024, height: 768 },
+      { name: 'desktop', label: 'Desktop', width: 1440, height: 900 },
+    ],
+  },
+})
 ```
 
-### Server Entry Point
+With `livePreview.injectRoute` enabled, the plugin adds `GET /api/theme/preview` (or your custom `routePath`).
 
-⚠️ **Import from `/server` for server components only:**
+- **Query parameters:**
+  - `pageSlug`
+  - `previewSecret` (or `preview`)
+  - `tenant`
+- **Secret:** read from `PREVIEW_SECRET` or `PAYLOAD_PREVIEW_SECRET`.
+- **Responses:**
+  - `307` redirects to the resolved client page
+  - `401` means a secret is configured but is missing or wrong
 
-```typescript
-import {
-  getThemeCriticalCSS,
-  getThemeCSS,
-  ServerThemeInjector,
-} from '@kilivi/payloadcms-theme-management/server'
+```txt
+/api/theme/preview?pageSlug=home&previewSecret=your-secret              → /
+/api/theme/preview?pageSlug=home&tenant=acme&previewSecret=your-secret  → /?tenant=acme
 ```
 
-> **Heads up:** Legacy helpers `getThemeCSSPath` and `generateThemePreloadLinks` are still exported for backwards compatibility but now return empty strings and emit console warnings. Prefer the inline CSS utilities above.
+**Testing tip:** preview is most useful when the previewed page uses many theme tokens: buttons, cards, banners, links and several heading levels. The repository's `dev-local` app includes `pnpm seed:theme`, which fills the `home` page with blocks like these.
 
-### Subpath Exports
+### Multi-tenant example
 
-```typescript
-// Direct field imports
-
-// Direct component imports
-import { ThemePreview } from '@kilivi/payloadcms-theme-management/components/ThemePreview'
-import { ThemeColorPickerField } from '@kilivi/payloadcms-theme-management/fields/ThemeColorPickerField'
-import { ThemeTokenSelectField } from '@kilivi/payloadcms-theme-management/fields/ThemeTokenSelectField'
+```ts
+themeManagementPlugin({
+  useStandaloneCollection: true,
+  standaloneCollectionSlug: 'appearance-settings',
+  livePreview: {
+    enabled: true,
+    injectRoute: true,
+    routePath: '/theme/preview',
+    pageCollection: 'pages',
+    pageSlug: 'home',
+    tenantField: 'tenant',
+    tenantQueryParam: 'tenant',
+  },
+  cacheRevalidation: {
+    enabled: true,
+    injectRoute: true,
+    routePath: '/theme/revalidate',
+    secret: process.env.THEME_REVALIDATE_SECRET,
+    tags: ['tenant:acme'],
+    paths: ['/'],
+  },
+})
 ```
 
-## Integration Examples
-
-### With Tailwind CSS
+See [MULTI_TENANT_GUIDE.md](./MULTI_TENANT_GUIDE.md) for shared vs per-tenant setups.
 
-#### tailwind.config.mjs
+## Cache revalidation
 
-```typescript
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/* eslint-disable @typescript-eslint/no-require-imports */
-/* eslint-disable import/no-anonymous-default-export */
-import defaultTheme from 'tailwindcss/defaultTheme'
+When `useStandaloneCollection: true`, the default cache tag is `global_{standaloneCollectionSlug}`. The plugin can inject `POST /api/theme/revalidate`:
 
-/** @type {import('tailwindcss').Config} */
-export default {
-  darkMode: ['class'],
-  content: [
-    './src/app/**/*.{ts,tsx}',
-    './src/components/**/*.{ts,tsx}',
-    './src/collections/**/*.{ts,tsx}',
-    './src/providers/**/*.{ts,tsx}',
-    './src/heros/**/*.{ts,tsx}',
-  ],
-  safelist: [
-    // Grid columns
-    'col-span-4',
-    'md:col-span-2',
-    'lg:col-span-4',
-    'lg:col-span-6',
-    'lg:col-span-8',
-    'lg:col-span-12',
-    // Border colors
-    'border-border',
-    'border-error',
-    'border-success',
-    'border-warning',
-    // Background colors
-    'bg-card',
-    'bg-error/30',
-    'bg-success/30',
-    'bg-warning/30',
-  ],
-  theme: {
-    container: {
-      center: true,
-      padding: {
-        DEFAULT: 'var(--layout-containerPadding)',
-        md: 'var(--layout-containerPaddingTablet)',
-        lg: 'var(--layout-containerPaddingDesktop)',
-      },
-      screens: {
-        sm: '640px',
-        md: '768px',
-        lg: '1024px',
-        xl: '1280px',
-      },
-    },
-    extend: {
-      colors: {
-        background: 'var(--background)',
-        foreground: 'var(--foreground)',
-        card: 'var(--card)',
-        'card-foreground': 'var(--card-foreground)',
-        popover: 'var(--popover)',
-        'popover-foreground': 'var(--popover-foreground)',
-        primary: 'var(--primary)',
-        'primary-foreground': 'var(--primary-foreground)',
-        secondary: 'var(--secondary)',
-        'secondary-foreground': 'var(--secondary-foreground)',
-        muted: 'var(--muted)',
-        'muted-foreground': 'var(--muted-foreground)',
-        accent: 'var(--accent)',
-        'accent-foreground': 'var(--accent-foreground)',
-        destructive: 'var(--destructive)',
-        'destructive-foreground': 'var(--destructive-foreground)',
-        border: 'var(--border)',
-        input: 'var(--input)',
-        ring: 'var(--ring)',
-        success: 'var(--success)',
-        'success-foreground': 'var(--success-foreground)',
-        warning: 'var(--warning)',
-        'warning-foreground': 'var(--warning-foreground)',
-        error: 'var(--error)',
-        'error-foreground': 'var(--error-foreground)',
-        info: 'var(--info)',
-        'info-foreground': 'var(--info-foreground)',
-      },
-      borderRadius: {
-        sm: 'var(--radius-small)',
-        DEFAULT: 'var(--radius-default)',
-        md: 'var(--radius-medium)',
-        lg: 'var(--radius-large)',
-      },
-      fontFamily: {
-        sans: ['var(--typography-fontFamily)', ...defaultTheme.fontFamily.sans],
-        heading: ['var(--typography-headingFamily)', ...defaultTheme.fontFamily.sans],
-        mono: ['var(--font-geist-mono)', ...defaultTheme.fontFamily.mono],
-      },
-      fontSize: {
-        base: ['var(--typography-baseFontSize)', { lineHeight: 'var(--typography-lineHeight)' }],
-      },
-      letterSpacing: {
-        tight: 'var(--typography-letterSpacing-tight)',
-        normal: 'var(--typography-letterSpacing-normal)',
-        wide: 'var(--typography-letterSpacing-wide)',
-      },
-      fontWeight: {
-        normal: 'var(--typography-fontWeights-normal)',
-        medium: 'var(--typography-fontWeights-medium)',
-        semibold: 'var(--typography-fontWeights-semibold)',
-        bold: 'var(--typography-fontWeights-bold)',
-      },
-      spacing: {
-        section: {
-          DEFAULT: 'var(--layout-sectionSpacing)',
-          md: 'var(--layout-sectionSpacingTablet)',
-          lg: 'var(--layout-sectionSpacingDesktop)',
-        },
-      },
-      transitionProperty: {
-        button: 'var(--components-button-transition)',
-      },
-      scale: {
-        'button-hover': 'var(--components-button-hover-scale)',
-      },
-      opacity: {
-        'button-hover': 'var(--components-button-hover-opacity)',
-      },
-      boxShadow: {
-        card: 'var(--components-card-shadow)',
-      },
-      padding: {
-        card: 'var(--components-card-padding)',
-        button: 'var(--components-button-padding)',
-        input: 'var(--components-input-padding)',
-      },
-      height: {
-        input: 'var(--components-input-height)',
-      },
-      typography: ({ theme }) => ({
-        DEFAULT: {
-          css: {
-            '--tw-prose-body': theme('colors.foreground'),
-            '--tw-prose-headings': theme('colors.foreground'),
-            '--tw-prose-lead': theme('colors.muted.foreground'),
-            '--tw-prose-links': theme('colors.primary'),
-            '--tw-prose-bold': theme('colors.foreground'),
-            '--tw-prose-counters': theme('colors.foreground'),
-            '--tw-prose-bullets': theme('colors.foreground'),
-            '--tw-prose-hr': theme('colors.border'),
-            '--tw-prose-quotes': theme('colors.foreground'),
-            '--tw-prose-quote-borders': theme('colors.border'),
-            '--tw-prose-captions': theme('colors.muted.foreground'),
-            '--tw-prose-code': theme('colors.foreground'),
-            '--tw-prose-pre-code': theme('colors.foreground'),
-            '--tw-prose-pre-bg': theme('colors.muted'),
-            '--tw-prose-th-borders': theme('colors.border'),
-            '--tw-prose-td-borders': theme('colors.border'),
-            h1: {
-              fontWeight: 'var(--typography-fontWeights-bold)',
-              marginBottom: '0.25em',
-              fontFamily: theme('fontFamily.heading'),
-              letterSpacing: 'var(--typography-letterSpacing-tight)',
-            },
-            h2: {
-              fontFamily: theme('fontFamily.heading'),
-              fontWeight: 'var(--typography-fontWeights-semibold)',
-              letterSpacing: 'var(--typography-letterSpacing-tight)',
-            },
-            h3: {
-              fontFamily: theme('fontFamily.heading'),
-              fontWeight: 'var(--typography-fontWeights-semibold)',
-              letterSpacing: 'var(--typography-letterSpacing-tight)',
-            },
-            h4: {
-              fontFamily: theme('fontFamily.heading'),
-              fontWeight: 'var(--typography-fontWeights-medium)',
-              letterSpacing: 'var(--typography-letterSpacing-normal)',
-            },
-          },
-        },
-        base: {
-          css: [
-            {
-              h1: { fontSize: '2.5rem' },
-              h2: { fontSize: '1.25rem' },
-            },
-          ],
-        },
-        md: {
-          css: [
-            {
-              h1: { fontSize: '3.5rem' },
-              h2: { fontSize: '1.5rem' },
-            },
-          ],
-        },
-        invert: {
-          css: {
-            '--tw-prose-body': 'var(--foreground)',
-            '--tw-prose-headings': 'var(--foreground)',
-            '--tw-prose-lead': 'var(--muted-foreground)',
-            '--tw-prose-links': 'var(--primary)',
-            '--tw-prose-bold': 'var(--foreground)',
-            '--tw-prose-counters': 'var(--foreground)',
-            '--tw-prose-bullets': 'var(--foreground)',
-            '--tw-prose-hr': 'var(--border)',
-            '--tw-prose-quotes': 'var(--foreground)',
-            '--tw-prose-quote-borders': 'var(--border)',
-            '--tw-prose-captions': 'var(--muted-foreground)',
-            '--tw-prose-code': 'var(--foreground)',
-            '--tw-prose-pre-code': 'var(--foreground)',
-            '--tw-prose-pre-bg': 'var(--muted)',
-            '--tw-prose-th-borders': 'var(--border)',
-            '--tw-prose-td-borders': 'var(--border)',
-          },
-        },
-      }),
-      animation: {
-        'accordion-down': 'accordion-down 0.2s ease-out',
-        'accordion-up': 'accordion-up 0.2s ease-out',
-      },
-      keyframes: {
-        'accordion-down': {
-          from: { height: 0 },
-          to: { height: 'var(--radix-accordion-content-height)' },
-        },
-        'accordion-up': {
-          from: { height: 'var(--radix-accordion-content-height)' },
-          to: { height: 0 },
-        },
-      },
-    },
+```ts
+themeManagementPlugin({
+  useStandaloneCollection: true,
+  cacheRevalidation: {
+    enabled: true,
+    injectRoute: true,
+    routePath: '/theme/revalidate',
+    secret: process.env.THEME_REVALIDATE_SECRET,
+    tags: ['tenant:default'],
+    paths: ['/'],
   },
-  plugins: [require('tailwindcss-animate'), require('@tailwindcss/typography')],
-}
-```
-
-#### globals.css
-
-```css
-@import 'tailwindcss';
-
-@config '../../../../../tailwind.config.mjs';
-
-@layer base {
-  /* Theme Configuration CSS Variables */
-  :root {
-    /* Font Scale Presets */
-    --font-scale-small: 0.875;
-    --font-scale-medium: 1;
-    --font-scale-large: 1.125;
-    --font-scale-xl: 1.25;
-
-    /* Spacing Presets */
-    --spacing-compact: 0.75;
-    --spacing-comfortable: 1;
-    --spacing-spacious: 1.25;
-    --spacing-xl: 1.5;
-
-    /* Animation Levels */
-    --animation-none-duration: 0ms;
-    --animation-reduced-duration: 100ms;
-    --animation-normal-duration: 200ms;
-    --animation-enhanced-duration: 300ms;
-
-    /* Dynamic theme configuration (set by JS) */
-    --theme-font-scale: var(--font-scale-medium);
-    --theme-spacing: var(--spacing-comfortable);
-    --theme-animation-level: normal;
-
-    /* Apply spacing multiplier to layout */
-    --layout-containerPadding-scaled: calc(
-      var(--layout-containerPadding) * var(--theme-spacing, 1)
-    );
-    --layout-containerPaddingTablet-scaled: calc(
-      var(--layout-containerPaddingTablet) * var(--theme-spacing, 1)
-    );
-    --layout-containerPaddingDesktop-scaled: calc(
-      var(--layout-containerPaddingDesktop) * var(--theme-spacing, 1)
-    );
-    --layout-sectionSpacing-scaled: calc(var(--layout-sectionSpacing) * var(--theme-spacing, 1));
-    --layout-sectionSpacingTablet-scaled: calc(
-      var(--layout-sectionSpacingTablet) * var(--theme-spacing, 1)
-    );
-    --layout-sectionSpacingDesktop-scaled: calc(
-      var(--layout-sectionSpacingDesktop) * var(--theme-spacing, 1)
-    );
-    --components-card-padding-scaled: calc(
-      var(--components-card-padding) * var(--theme-spacing, 1)
-    );
-    --components-button-padding-scaled: var(--components-button-padding);
-    --components-input-padding-scaled: var(--components-input-padding);
-  }
-
-  *,
-  *::before,
-  *::after {
-    box-sizing: border-box;
-    margin: 0;
-    padding: 0;
-    @apply border-border;
-  }
-
-  html {
-    -webkit-text-size-adjust: 100%;
-    font-size: calc(var(--typography-baseFontSize, 16px) * var(--theme-font-scale, 1));
-    line-height: var(--typography-lineHeight, 1.5);
-    font-family: var(--typography-fontFamily, system-ui, sans-serif);
-    visibility: hidden;
-  }
-
-  /* Animation level controls */
-  [data-animation-level='none'] * {
-    animation-duration: var(--animation-none-duration) !important;
-    transition-duration: var(--animation-none-duration) !important;
-  }
-
-  [data-animation-level='reduced'] * {
-    animation-duration: var(--animation-reduced-duration) !important;
-    transition-duration: var(--animation-reduced-duration) !important;
-  }
-
-  [data-animation-level='normal'] * {
-    animation-duration: var(--animation-normal-duration);
-    transition-duration: var(--animation-normal-duration);
-  }
-
-  [data-animation-level='enhanced'] * {
-    animation-duration: var(--animation-enhanced-duration);
-    transition-duration: var(--animation-enhanced-duration);
-  }
-
-  h1,
-  h2,
-  h3,
-  h4,
-  h5,
-  h6 {
-    font-family: var(
-      --typography-headingFamily,
-      var(--typography-fontFamily, system-ui, sans-serif)
-    );
-    font-weight: var(--typography-fontWeights-bold, 700);
-    line-height: 1.2;
-  }
-
-  /* Prevent flash of unstyled content except for Storybook */
-  :root:not([data-theme]):not([data-theme-mode]):not(.sb-show-main) {
-    visibility: hidden;
-  }
-
-  :root[data-theme][data-theme-mode],
-  .sb-show-main {
-    visibility: visible;
-  }
-
-  html:not(.sb-show-main) {
-    opacity: 0;
-  }
-
-  html[data-theme-mode='dark'],
-  html[data-theme-mode='light'],
-  html.sb-show-main {
-    opacity: 1;
-    transition: opacity 0ms;
-  }
-
-  /* Force immediate opacity when JS is disabled */
-  html:not([data-theme-mode]) {
-    opacity: 1;
-  }
-
-  /* Media queries for responsive layout */
-  @media (min-width: 640px) {
-    :root {
-      --layout-containerPadding: var(--layout-containerPaddingTablet, 2rem);
-      --layout-sectionSpacing: var(--layout-sectionSpacingTablet, 3rem);
-    }
-  }
-
-  @media (min-width: 1024px) {
-    :root {
-      --layout-containerPadding: var(--layout-containerPaddingDesktop, 2rem);
-      --layout-sectionSpacing: var(--layout-sectionSpacingDesktop, 4rem);
-    }
-  }
-
-  /* Ensure dark mode styles take precedence */
-  html[data-theme-mode='dark'] {
-    color-scheme: dark;
-  }
-
-  /* Native View Transitions API - React 19 */
-  @view-transition {
-    navigation: auto;
-  }
-
-  /* Smooth fade transition for page navigation */
-  ::view-transition-old(root),
-  ::view-transition-new(root) {
-    animation-duration: 0.3s;
-    animation-timing-function: ease-in-out;
-  }
-
-  ::view-transition-old(root) {
-    animation-name: fade-out;
-  }
-
-  ::view-transition-new(root) {
-    animation-name: fade-in;
-  }
-
-  @keyframes fade-out {
-    to {
-      opacity: 0;
-    }
-  }
-
-  @keyframes fade-in {
-    from {
-      opacity: 0;
-    }
-  }
-
-  /* Respect user's reduced motion preference */
-  @media (prefers-reduced-motion: reduce) {
-    ::view-transition-old(root),
-    ::view-transition-new(root) {
-      animation-duration: 0.01ms !important;
-    }
-  }
-}
+})
 ```
 
-### Fetching Theme Configuration
-
-The recommended way to fetch theme configuration is using Payload's native API with Next.js caching:
+### Next.js server caching helper
 
-```typescript
+```tsx
+import {
+  createCachedThemeFetcher,
+  ServerThemeInjector,
+} from '@kilivi/payloadcms-theme-management/server'
 import configPromise from '@payload-config'
 import { getPayload } from 'payload'
-import { unstable_cache } from 'next/cache'
 
-// Cached theme fetcher with automatic invalidation
-const getCachedTheme = unstable_cache(
-  async () => {
+const getCachedTheme = createCachedThemeFetcher({
+  globalSlug: 'appearance-settings',
+  revalidate: 3600,
+  loadAppearanceSettings: async () => {
     const payload = await getPayload({ config: configPromise })
-    const global = await payload.findGlobal({
-      slug: 'appearance-settings', // or 'your-global-slug'
-    })
-    return global?.themeConfiguration
-  },
-  ['appearance-settings'],
-  {
-    tags: ['global_appearance-settings'],
-    revalidate: 3600, // Revalidate every hour
+    return payload.findGlobal({ slug: 'appearance-settings' })
   },
-)
+})
 
-// Use in your layout
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
   const themeConfiguration = await getCachedTheme()
-  // Use themeConfiguration...
+
+  return (
+    <html lang="en">
+      <head>
+        <ServerThemeInjector themeConfiguration={themeConfiguration} />
+      </head>
+      <body>{children}</body>
+    </html>
+  )
 }
 ```
 
-**Legacy Helper (still available):**
+### Fetching the configuration
 
-If you need the helper function, `fetchThemeConfiguration` is still exported:
-
-```typescript
+```ts
 import { fetchThemeConfiguration } from '@kilivi/payloadcms-theme-management'
 
-// Simple fetch without caching
-const theme = await fetchThemeConfiguration({
+// Single tenant
+const themeConfiguration = await fetchThemeConfiguration({
+  useGlobal: true,
   collectionSlug: 'appearance-settings',
+})
+
+// Multi-tenant
+const tenantThemeConfiguration = await fetchThemeConfiguration({
   useGlobal: true,
+  collectionSlug: 'appearance-settings',
+  tenantSlug: 'acme',
 })
 ```
 
-However, prefer the native Payload API + `unstable_cache` approach for better performance and automatic invalidation support.
-
-### Custom Theme Preset
+## Plugin options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `true` | Enables or disables the plugin |
+| `targetCollection` | `string` | `'site-settings'` | Collection slug for tab mode |
+| `useStandaloneCollection` | `boolean` | `false` | Creates a standalone global instead of injecting a tab |
+| `standaloneCollectionSlug` | `string` | `'appearance-settings'` | Global slug in standalone mode |
+| `standaloneCollectionLabel` | `string \| Record<string, string>` | translated label | Label of the standalone global |
+| `themePresets` | `ThemePreset[]` | built-in presets | Custom preset list |
+| `defaultTheme` | `string` | `'cool'` | Default preset name |
+| `includeColorModeToggle` | `boolean` | `true` | Colour mode section (light/dark tokens, audit, export) |
+| `includeCustomCSS` | `boolean` | `true` | Enables the custom CSS field |
+| `enableAdvancedFeatures` | `boolean` | `true` | Advanced controls such as animation level |
+| `customThemeConfigurationFields` | `Field[]` | `undefined` | Extra fields appended inside the `themeConfiguration` group |
+| `customThemeConfigurationSections` | `Array<{ label; fields; initCollapsed?; description? }>` | `undefined` | Extra collapsible sections inside the group |
+| `enableLogging` | `boolean` | `false` | Logs plugin actions |
+| `livePreview` | `boolean \| ThemeManagementLivePreviewOptions` | `true` | Live preview URL behaviour |
+| `cacheRevalidation` | `boolean \| ThemeManagementCacheRevalidationOptions` | on in standalone mode | Cache invalidation endpoint, tags and paths |
+| `i18n` | `ThemeManagementI18nOptions` | `undefined` | Extend or override admin translations |
+| `includeBrandIdentity` | `boolean` | `false` | Reserved for future use |
+
+### `livePreview` options
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `enabled` | `boolean` | `true` |
+| `injectRoute` | `boolean` | `false` |
+| `routePath` | `string` | `'/theme/preview'` |
+| `pageCollection` | `string` | `'pages'` |
+| `pageSlug` | `string` | `'home'` |
+| `fallbackToFirstPage` | `boolean` | `true` |
+| `tenantField` | `string` | `'tenant'` |
+| `tenantQueryParam` | `string` | `'tenant'` |
+| `breakpoints` | `Array<{ name; label; width; height }>` | `undefined` |
+| `url` | `(args) => string \| Promise<string>` | slug-based URL |
+
+### `cacheRevalidation` options
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `enabled` | `boolean` | `true` in standalone mode, otherwise `false` |
+| `injectRoute` | `boolean` | `true` |
+| `routePath` | `string` | `'/theme/revalidate'` |
+| `secret` | `string` | `undefined` |
+| `tags` | `string[]` | `[global_{slug}]` |
+| `paths` | `string[]` | `[]` |
+
+## Internationalization
+
+The plugin ships with **English (`en`)** and **Czech (`cs`)** admin translations. It registers them in Payload's native `config.i18n` under the `theme-management` namespace.
+
+- Every admin string follows the active admin language, including field labels, the pickers, the audit, the import drawer and the font guides.
+- Localised label objects (`{ en, cs, … }`) resolve to the admin language first, then to English.
+
+To add languages or override strings, use the `i18n` option. It is deep-merged over the built-in strings, and missing keys fall back to English.
 
-```typescript
-import type { ThemePreset } from '@kilivi/payloadcms-theme-management'
-
-const myTheme: ThemePreset = {
-  name: 'my-custom-theme',
-  label: 'My Custom Theme',
-  colors: {
-    primary: { h: 220, s: 70, l: 50 },
-    secondary: { h: 180, s: 60, l: 45 },
-    // ... other colors
-  },
-  borderRadius: 'rounded',
-  typography: {
-    heading: 'Poppins',
-    body: 'Inter',
-    code: 'Fira Code',
-  },
-}
+```ts
+import { de } from '@payloadcms/translations/languages/de'
 
-// Use in plugin config
 themeManagementPlugin({
-  themePresets: [myTheme],
-  defaultTheme: 'my-custom-theme',
+  i18n: {
+    translations: {
+      de: { tabLabel: 'Darstellung', ui: { lightMode: 'Heller Modus' } },
+      en: { tabLabel: 'Theme' }, // override a built-in string
+    },
+    supportedLanguages: { de }, // optional: register a new admin language
+  },
 })
 ```
 
-## Migrating from Older Versions
-
-See [MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md) for detailed migration instructions.
-
-### Key Changes in v0.1.9+
-
-- **Server components must import from `/server`**
-- Added `server-only` package to prevent client bundling errors
-- Removed `ServerThemeInjector` from main entry point
+Full guide: [docs/TRANSLATIONS.md](./docs/TRANSLATIONS.md)
 
-```diff
-- import { ServerThemeInjector } from '@kilivi/payloadcms-theme-management'
-+ import { ServerThemeInjector } from '@kilivi/payloadcms-theme-management/server'
-```
-
-## Testing
+## Appearance controls
 
-See [TEST_APP_GUIDE.md](./docs/TEST_APP_GUIDE.md) for instructions on creating a test application.
+| Section | Admin group | Fields |
+| --- | --- | --- |
+| Visual effects | `themeConfiguration.visualEffects` | effectStyle, shadowIntensity, backdropBlur, borderStyle, borderWidth, glassOpacity |
+| Component styles | `themeConfiguration.componentStyles` | buttonVariant, buttonSize, cardStyle, cardHoverEffect, navbarStyle, footerStyle, imageStyle, linkStyle, enableScrollReveal, enableHoverAnimations |
+| Typography | `themeConfiguration.typography` | bodyFont, headingFont, bodyFontCustom, headingFontCustom, baseFontSize, lineHeight |
 
-## Troubleshooting
+`heroBackground` (hero style, patterns, dividers) is part of the `ThemeHeroBackground` type and the CSS generator, but the tab has no admin fields for it. Add them through `customThemeConfigurationSections` if you need them.
 
-### Type Conflicts: `Type 'SiteSetting' is not assignable to type 'SiteSetting'`
+Full reference: [docs/APPEARANCE_CONTROLS.md](./docs/APPEARANCE_CONTROLS.md)
 
-**Problem:** You see errors about incompatible types even though you're passing the correct data structure.
+```tsx
+import { fetchThemeConfiguration } from '@kilivi/payloadcms-theme-management'
 
-**Why This Happens:** Your app's generated `payload-types.ts` might have slightly different type definitions than the plugin's (e.g., different font options, field variations).
+const theme = await fetchThemeConfiguration({ collectionSlug: 'site-settings' })
 
-**Solution:** Update to v0.1.11+ which uses generic types instead of strict payload-types:
+const effect = theme?.visualEffects?.effectStyle ?? 'flat'
+const button = theme?.componentStyles?.buttonVariant ?? 'filled'
 
-```bash
-pnpm update @kilivi/payloadcms-theme-management@latest
+return (
+  <html data-effect={effect} data-button={button}>
+    ...
+  </html>
+)
 ```
 
-The plugin now accepts any compatible theme configuration structure, regardless of your Payload version or type variations. See [TYPE_INDEPENDENCE_GUIDE.md](./docs/TYPE_INDEPENDENCE_GUIDE.md) for technical details.
-
-### `Module not found: Can't resolve 'fs/promises'`
+## Theme presets
 
-**Solution:** Make sure you're using v0.1.9+ and importing server components from `/server`:
+Built-in presets are exported as `allThemePresets`, and style presets as `allStylePresets`:
 
-```typescript
-import { ServerThemeInjector } from '@kilivi/payloadcms-theme-management/server'
-```
-
-Then clear your cache:
-
-```bash
-rm -rf .next node_modules/.cache
-pnpm install
+```ts
+import { allStylePresets, allThemePresets } from '@kilivi/payloadcms-theme-management'
 ```
 
-### Theme Not Applying
-
-1. Verify `ServerThemeInjector` is in your `<head>` tag
-2. Check that site settings exist with theme configuration
-3. Inspect page source - should see `<style>` tag with CSS variables
-4. Ensure Tailwind/CSS is configured to use the CSS variables
+Editors can also import extra presets as JSON (*Custom theme presets* section). They are merged into the theme picker, and they override built-in presets that have the same `name`.
 
-### TypeScript Errors
+Full preset reference: [docs/THEME_PRESETS_EXTENDED.md](./docs/THEME_PRESETS_EXTENDED.md)
 
-```bash
-# Regenerate Payload types
-pnpm payload generate:types
+## Visitor components
 
-# Restart TypeScript server
-# VS Code: Ctrl+Shift+P → "TypeScript: Restart TS Server"
+```tsx
+import ColorModeToggle from '@kilivi/payloadcms-theme-management/components/ColorModeToggle'
+import ThemeSwitcher from '@kilivi/payloadcms-theme-management/components/ThemeSwitcher'
 ```
 
-## Documentation
+## Public API
 
-- [Type Independence Guide](./docs/TYPE_INDEPENDENCE_GUIDE.md) - Understanding type safety without coupling
-- [Migration Guide](./docs/MIGRATION_GUIDE.md) - Upgrading from older versions
-- [Test App Guide](./docs/TEST_APP_GUIDE.md) - Create a test application
-- [Server/Client Separation](./docs/SERVER_CLIENT_SEPARATION.md) - Technical details
-- [Build Setup](./docs/BUILD_SETUP.md) - Build configuration details
+### Main package
 
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build the plugin
-pnpm build
-
-# Watch mode for development
-pnpm dev
+```ts
+import {
+  allStylePresets,
+  allThemePresets,
+  fetchThemeConfiguration,
+  generateThemeColorsCss,
+  generateThemeCSS,
+  getAvailableThemePresets,
+  getThemeHtmlAttributes,
+  getThemePreset,
+  getThemeStyles,
+  resolveThemeConfiguration,
+  themeManagementPlugin,
+  ThemeProvider,
+} from '@kilivi/payloadcms-theme-management'
 
-# Clean build artifacts
-pnpm clean
+import type {
+  SiteThemeConfiguration,
+  ThemeComponentStyles,
+  ThemeHeroBackground,
+  ThemeVisualEffects,
+} from '@kilivi/payloadcms-theme-management'
 ```
 
-## Contributing
-
-Contributions are welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
-
-## Troubleshooting
+### Server package
 
-### Common Issues
-
-**Error: "right-hand side of 'in' should be an object, got undefined"**
-
-This is a known Payload CMS issue related to user preferences. See [TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) for solutions.
-
-**Quick Fix:** Go to `/admin/account` and click "Reset Preferences" at the bottom of the page.
+```ts
+import {
+  createCachedThemeFetcher,
+  getThemeCacheTag,
+  getThemeCriticalCSS,
+  getThemeCSS,
+  revalidateThemeCache,
+  ServerThemeInjector,
+} from '@kilivi/payloadcms-theme-management/server'
+```
 
-## License
+Always import server-only helpers from `/server`.
 
-Apache-2.0
+## Migrating from `@kilivi-dev`
 
-## Author
+The API is unchanged. Only the package name differs.
 
-Created for Payload CMS v3 applications.
+1. Swap the dependency:
 
-## Links
+   ```bash
+   pnpm remove @kilivi-dev/payloadcms-theme-management
+   pnpm add @kilivi/payloadcms-theme-management
+   ```
 
-- [NPM Package](https://www.npmjs.com/package/@kilivi/payloadcms-theme-management)
-- [GitHub Repository](https://github.com/vitakili/payload-plugins)
-- [Payload CMS](https://payloadcms.com)
+2. Replace the import prefix in your code: `@kilivi-dev/payloadcms-theme-management` → `@kilivi/payloadcms-theme-management`. This covers `/server`, `/components/*` and `/fields/*`.
+3. Regenerate the admin import map so Payload resolves the admin components under the new name:
 
-## Changelog
+   ```bash
+   pnpm payload generate:importmap
+   ```
 
-### v1.0.2 (Latest)
+4. If you list the package in `next.config` under `transpilePackages`, rename it there too.
 
-- ✅ **Added:** Automatic cache invalidation for standalone globals
-- ✅ **Fixed:** Correct Payload CMS v3 API usage (findGlobal instead of non-existent findBySlug)
-- ✅ **Improved:** Multi-tenant documentation with proper examples
-- ✅ **Improved:** Cache optimization examples with unstable_cache
-- ✅ **Updated:** README and Multi-Tenant guide with accurate API methods
+Stored data does not need a migration: field names and database columns stay the same.
 
-### v1.0.0
+## Notes
 
-- ✅ **Added:** Standalone Global Support — create separate appearance settings as a global
-- ✅ **Added:** Auto-populate Light/Dark colors when selecting a theme
-- ✅ **Added:** Multi-tenant support and tenant-aware theme fetching
-- ✅ **Fixed:** Cleaner data structure for improved API integration
-- ✅ **Added:** Live Theme Preview at `/admin/theme-preview` (real-time updates)
-- ✅ **Added:** Professional color picker (react-colorful)
-- ✅ **Improved:** shadcn/ui and TweakCN compatibility
-- ✅ **Improved:** SSR theme injection, zero FOUC, and performance optimizations
-- ✅ **Added:** Server/client component separation
-- ✅ **Added:** `server-only` package to prevent bundling errors
-- ✅ **Changed:** `ServerThemeInjector` now exported from `/server` entry
+- For strict preview security, set `PREVIEW_SECRET` and enable `livePreview.injectRoute`.
+- For multi-tenant apps, use `tenantField` and `tenantQueryParam` to keep preview URLs tenant-aware.
+- Task-focused guides for AI coding assistants live in `.claude/skills/`.
 
-### v0.6.0
+## License
 
-- Initial release with core theming functionality
+MIT