tailor-platform · IzumiSy · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/.changeset/theme-mode-palette-axes.md b/.changeset/theme-mode-palette-axes.md
@@ -0,0 +1,27 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Introduce theming support — **ColorTheme** axis, static **theme palettes** via CSS imports, a new `AppearanceSwitcher` component, and bundled Inter variable fonts.
+
+#### ColorTheme (end-user preference, persisted)
+
+`ColorTheme` (`"light" | "dark" | "system"`) is the end-user color mode preference. Applied to `<html>` as `.light` / `.dark` class.
+
+- `<AppShell defaultColorTheme="system">` sets the initial preference; user choice is persisted to localStorage.
+- `useTheme()` hook returns `{ theme, resolvedTheme, setTheme }`.
+
+#### Theme Palettes (static CSS imports)
+
+Each palette (`default`, `cream`, `bloom`) ships both light and dark variants.
+Select a palette by importing its CSS file — no prop needed:
+
+```ts
+import "@tailor-platform/app-shell/themes/cream";
+```
+
+The default palette is included automatically via `@tailor-platform/app-shell/styles`.
+
+#### AppearanceSwitcher
+
+- New `<AppearanceSwitcher />` component for toggling color theme (light / dark / system).
diff --git a/.changeset/theme-token-tiers.md b/.changeset/theme-token-tiers.md
@@ -0,0 +1,5 @@
+---
+"@tailor-platform/app-shell": patch
+---
+
+Set explicit `--accent` values per palette and mode, reorganise palette CSS into numbered tiers with a `_template.css` authoring guide, add `--alert-*` semantic tokens to the default palette, and wire `Alert` variants to those tokens (including lighter dark-mode foregrounds).
diff --git a/docs/components/alert.md b/docs/components/alert.md
@@ -78,7 +78,7 @@ Each variant automatically renders a contextual icon:
 
 | Variant   | Automatic Icon      | Color palette   |
 | --------- | ------------------- | --------------- |
-| `neutral` | Message circle icon | Secondary/muted |
+| `neutral` | Message circle icon | Muted surface   |
 | `success` | Check circle icon   | Green           |
 | `warning` | Alert triangle icon | Yellow          |
 | `error`   | X circle icon       | Red/destructive |

diff --git a/docs/concepts/styling-theming.md b/docs/concepts/styling-theming.md
@@ -60,3 +60,21 @@ These properties are defined in `:root` and can be overridden in your own CSS:
   --z-popup: 100;
 }
 ```
+
+## Adding a palette
+
+Theme tokens live in `packages/core/src/assets/themes/`. Copy `_template.css` to start a new palette — it lists exactly which sections to fill in for light and dark mode.
+
+| Section               | Required?             | What to set                                                   |
+| --------------------- | --------------------- | ------------------------------------------------------------- |
+| **1. Brand**          | Yes                   | `primary`, `secondary`, `accent` (+ foregrounds) — both modes |
+| **2. Shell gradient** | Branded palettes only | `--shell-gradient-base`, `--shell-gradient-tint`              |
+| **3. Derived**        | Copy verbatim         | Ring, sidebar aliases, gradient stops — do not edit           |
+| **4. System**         | Tune or copy default  | Surfaces: background, card, popover, muted, borders           |
+| **5. Palette**        | Optional              | Radius, chart colors, shadows                                 |
+| **6. Semantic**       | Do not duplicate      | Status and alert tokens inherit from `default.css`            |
+| **7. Structural**     | Branded palettes      | Copy `@layer` blocks from `bloom.css` for gradient shell      |
+
+Then `@import` the new file in `theme.css` and set `defaultThemePalette` on `<AppShell />`.
+
+Preview token values at `/custom-page/color` in the Next.js example app.
diff --git a/e2e/app/src/index.css b/e2e/app/src/index.css
@@ -1,3 +1,2 @@
 @import "tailwindcss";
 @import "@tailor-platform/app-shell/styles";
-@import "@tailor-platform/app-shell/theme.css";
diff --git a/examples/nextjs-app/src/app/layout.tsx b/examples/nextjs-app/src/app/layout.tsx
@@ -1,5 +1,6 @@
 import type { Metadata } from "next";
 import "@tailor-platform/app-shell/styles";
+import "@tailor-platform/app-shell/themes/cream";
 import "./globals.css";
 
 export const metadata: Metadata = {

diff --git a/examples/nextjs-app/src/modules/custom-module.tsx b/examples/nextjs-app/src/modules/custom-module.tsx
@@ -21,6 +21,7 @@ import { dropdownComponentsDemoResource } from "./pages/dropdown-demo";
 import { formComponentsDemoResource, zodRHFFormDemoResource } from "./pages/form-demo";
 import { csvImporterDemoResource } from "./pages/csv-importer-demo";
 import { dataTableDemoResource } from "./pages/data-table-demo";
+import { colorDemoResource } from "./pages/color-demo";
 
 export const customPageModule = defineModule({
   path: "custom-page",
@@ -40,6 +41,17 @@ export const customPageModule = defineModule({
           <p>
             <Link to="/custom-page/sub1/sub1-1/123">{t("goToDynamicPage")}</Link>
           </p>
+          <p>
+            <Link
+              to="/custom-page/color"
+              style={{
+                color: "hsl(var(--primary))",
+                textDecoration: "underline",
+              }}
+            >
+              Color tokens (swatches & layers)
+            </Link>
+          </p>
           <p>
             <Link
               to="/custom-page/purchase-order-demo"
@@ -217,6 +229,7 @@ export const customPageModule = defineModule({
     subPageResource,
     hiddenResource,
     adminOnlyResource,
+    colorDemoResource,
     purchaseOrderDemoResource,
     actionPanelDemoResource,
     metricCardDemoResource,