Align theme docs and palette templates

docs/concepts/styling-theming.md

@@ -5,18 +5,24 @@ description: Learn how to style your AppShell application using Tailwind CSS v4
 
 # Styling and Theming
 
-Styling is done using Tailwind CSS v4. AppShell exports a `theme.css` file which includes Tailor's preferred color palette and CSS variables.
+Styling is done using Tailwind CSS v4. AppShell exports `@tailor-platform/app-shell/styles`, which includes the default palette and CSS variables.
 
-To configure in your AppShell application, in your global.css or top-level tailwind css file, include this theme.css
+To configure your application, import AppShell styles from your global CSS or top-level Tailwind CSS file:
 
-Example:
+```css
+@import "tailwindcss";
+@import "@tailor-platform/app-shell/styles";
+```
+
+If you want a branded palette, import exactly one theme file after `styles`:
 
 ```css
-@import "@tailor-platform/app-shell/theme.css"; /* <-- Include this line */
 @import "tailwindcss";
+@import "@tailor-platform/app-shell/styles";
+@import "@tailor-platform/app-shell/themes/bloom";
 ```
 
-After including this, your Application's Tailwind will apply the custom colors to to the utility classes.
+After including this, your application's Tailwind utilities will resolve against the active AppShell tokens.
 
 E.g.
 
@@ -108,8 +114,8 @@ These properties are defined in `:root` and can be overridden in your own CSS:
 
 ```css
 /* your-app/globals.css */
-@import "@tailor-platform/app-shell/theme.css";
 @import "tailwindcss";
+@import "@tailor-platform/app-shell/styles";
 
 :root {
   --z-popup: 100;
@@ -120,16 +126,15 @@ These properties are defined in `:root` and can be overridden in your own CSS:
 
 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 />`.
+| 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. System**         | Tune or copy default  | Surfaces: background, card, popover, muted, borders                            |
+| **4. Palette**        | Optional              | Radius, chart colors, shadows                                                  |
+| **5. Semantic**       | Do not duplicate      | Status and alert tokens inherit from `default.css`                             |
+| **6. Structural**     | Branded palettes      | Copy the structural override block from `bloom.css` or `cream.css` when needed |
+
+A palette is selected by CSS import, not by an AppShell prop. Import exactly one theme file after `@tailor-platform/app-shell/styles`; if you import none, the default palette from `styles` is used.
 
 Preview token values at `/custom-page/color` in the Next.js example app.

examples/nextjs-app/src/modules/pages/color-demo.tsx

@@ -176,20 +176,17 @@ const ColorDemoPage = () => {
               <ColorSwatch name="chart-5" bgVar="--chart-5" fgVar="--foreground" />
             </SwatchSection>
 
+            {/* Show author-facing gradient inputs (`base` + `tint`) here.
+                `start` / `end` are derived from them in the theme CSS. */}
             <SwatchSection title="Shell gradient">
               <ColorSwatch
                 name="shell-gradient-base"
                 bgVar="--shell-gradient-base"
                 fgVar="--foreground"
               />
               <ColorSwatch
-                name="shell-gradient-start"
-                bgVar="--shell-gradient-start"
-                fgVar="--foreground"
-              />
-              <ColorSwatch
-                name="shell-gradient-end"
-                bgVar="--shell-gradient-end"
+                name="shell-gradient-tint"
+                bgVar="--shell-gradient-tint"
                 fgVar="--foreground"
               />
             </SwatchSection>
@@ -295,7 +292,18 @@ const ColorDemoPage = () => {
                     padding: "0.75rem",
                     borderRadius: "var(--radius-md)",
                     backgroundColor: "var(--shell-gradient-base)",
-                    backgroundImage: `linear-gradient(to bottom, var(--shell-gradient-start), var(--shell-gradient-end))`,
+                    // Keep the preview formula inline so this demo reads the
+                    // same author-facing tokens palette files set: `base` + `tint`.
+                    backgroundImage: `linear-gradient(
+                      to bottom,
+                      color-mix(in srgb, var(--shell-gradient-base) 55%, var(--shell-gradient-tint)) 0%,
+                      color-mix(in srgb, var(--shell-gradient-base) 45%, var(--shell-gradient-tint)) 20%,
+                      color-mix(in srgb, var(--shell-gradient-base) 30%, var(--shell-gradient-tint)) 40%,
+                      color-mix(in srgb, var(--shell-gradient-base) 15%, var(--shell-gradient-tint)) 55%,
+                      color-mix(in srgb, var(--shell-gradient-base) 6%, var(--shell-gradient-tint)) 65%,
+                      var(--shell-gradient-tint) 70%,
+                      var(--shell-gradient-tint) 100%
+                    )`,
                     border: "1px solid var(--border)",
                     maxWidth: "14rem",
                   }}

packages/core/src/assets/theme.css

@@ -1,7 +1,9 @@
 /**
  * Theme system
  *
- * Palettes live in ./themes/*.css. Copy ./_template.css to add a new one.
+ * `@tailor-platform/app-shell/styles` includes the default palette.
+ * Import exactly one optional override from `./themes/*.css` after styles
+ * (for example `@tailor-platform/app-shell/themes/cream`).
  *
  * Palette tiers:
  *
@@ -16,8 +18,8 @@
  * Inherited from default.css — do not duplicate in new palettes:
  *   --ring, --sidebar-*, --status-*, --alert-*.
  *
- * Mode: `.dark` on <html>. Palette: import one theme file after styles
- * (e.g. `@tailor-platform/app-shell/themes/cream`).
+ * Light/dark mode is controlled separately via `.dark` on <html>.
+ * Palette selection is by CSS import; there is no runtime palette prop.
  */
 @import "./themes/default.css" layer(theme.defaults);
 

packages/core/src/assets/themes/_template.css

@@ -13,12 +13,11 @@
  *    from `default.css` for neutral palettes, or from `bloom.css` / `cream.css`
  *    as a starting point for branded shells. Set both modes.
  * 5. Optional: section 4 (PALETTE) — radius, chart hues, shadow tint.
- * 6. `@import "./themes/{name}.css"` in `theme.css`.
- * 7. Set `defaultThemePalette="{name}"` on `<AppShell />` (or let users switch).
+ * 6. Import `@tailor-platform/app-shell/themes/{name}` after
+ *    `@tailor-platform/app-shell/styles` in the consuming app.
  *
  * DO NOT SET (inherited from `:root` in default.css):
- *   --ring, --sidebar-*, --status-*, --alert-*,
- *   --destructive-foreground formulas in light mode
+ *   --ring, --sidebar-*, --status-*, --alert-*
  *
  * PREVIEW: `/custom-page/color` in the Next.js example app.
  * ═══════════════════════════════════════════════════════════════════════════
@@ -32,7 +31,7 @@
   --primary-foreground: /* contrast text on primary */;
   --secondary: /* filled secondary actions, badges */;
   --secondary-foreground: /* contrast text on secondary */;
-  --accent: /* menu/sidebar hover & selection — tune by eye, not derived */;
+  --accent: /* menu/sidebar hover & selection — tune by eye */;
   --accent-foreground: /* contrast text on accent */;
 
   /* ── 2. SHELL GRADIENT — optional; omit for flat palettes like default ── */
@@ -112,6 +111,6 @@
 }
 
 /*
- * Optional: copy the structural overrides block from bloom.css or cream.css
+ * Optional: copy the structural override block from bloom.css or cream.css
  * when using a shell gradient (transparent sidebar, squircle, etc.).
  */