Skip to content

Commit 761da47

Browse files
IzumiSyIzumiSy
authored
Align theme docs and palette templates (#330)
* Align theme docs and palette templates * Add theme intent comments to color demo * Remove changeset for unreleased theme cleanup * Remove unused shell gradient derived vars
1 parent 190e8f2 commit 761da47

4 files changed

Lines changed: 48 additions & 34 deletions

File tree

‎docs/concepts/styling-theming.md‎

Lines changed: 22 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,24 @@ description: Learn how to style your AppShell application using Tailwind CSS v4
55

66
# Styling and Theming
77

8-
Styling is done using Tailwind CSS v4. AppShell exports a `theme.css` file which includes Tailor's preferred color palette and CSS variables.
8+
Styling is done using Tailwind CSS v4. AppShell exports `@tailor-platform/app-shell/styles`, which includes the default palette and CSS variables.
99

10-
To configure in your AppShell application, in your global.css or top-level tailwind css file, include this theme.css
10+
To configure your application, import AppShell styles from your global CSS or top-level Tailwind CSS file:
1111

12-
Example:
12+
```css
13+
@import "tailwindcss";
14+
@import "@tailor-platform/app-shell/styles";
15+
```
16+
17+
If you want a branded palette, import exactly one theme file after `styles`:
1318

1419
```css
15-
@import "@tailor-platform/app-shell/theme.css"; /* <-- Include this line */
1620
@import "tailwindcss";
21+
@import "@tailor-platform/app-shell/styles";
22+
@import "@tailor-platform/app-shell/themes/bloom";
1723
```
1824

19-
After including this, your Application's Tailwind will apply the custom colors to to the utility classes.
25+
After including this, your application's Tailwind utilities will resolve against the active AppShell tokens.
2026

2127
E.g.
2228

@@ -108,8 +114,8 @@ These properties are defined in `:root` and can be overridden in your own CSS:
108114

109115
```css
110116
/* your-app/globals.css */
111-
@import "@tailor-platform/app-shell/theme.css";
112117
@import "tailwindcss";
118+
@import "@tailor-platform/app-shell/styles";
113119

114120
:root {
115121
--z-popup: 100;
@@ -120,16 +126,15 @@ These properties are defined in `:root` and can be overridden in your own CSS:
120126

121127
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.
122128

123-
| Section | Required? | What to set |
124-
| --------------------- | --------------------- | ------------------------------------------------------------- |
125-
| **1. Brand** | Yes | `primary`, `secondary`, `accent` (+ foregrounds) — both modes |
126-
| **2. Shell gradient** | Branded palettes only | `--shell-gradient-base`, `--shell-gradient-tint` |
127-
| **3. Derived** | Copy verbatim | Ring, sidebar aliases, gradient stops — do not edit |
128-
| **4. System** | Tune or copy default | Surfaces: background, card, popover, muted, borders |
129-
| **5. Palette** | Optional | Radius, chart colors, shadows |
130-
| **6. Semantic** | Do not duplicate | Status and alert tokens inherit from `default.css` |
131-
| **7. Structural** | Branded palettes | Copy `@layer` blocks from `bloom.css` for gradient shell |
132-
133-
Then `@import` the new file in `theme.css` and set `defaultThemePalette` on `<AppShell />`.
129+
| Section | Required? | What to set |
130+
| --------------------- | --------------------- | ------------------------------------------------------------------------------ |
131+
| **1. Brand** | Yes | `primary`, `secondary`, `accent` (+ foregrounds) — both modes |
132+
| **2. Shell gradient** | Branded palettes only | `--shell-gradient-base`, `--shell-gradient-tint` |
133+
| **3. System** | Tune or copy default | Surfaces: background, card, popover, muted, borders |
134+
| **4. Palette** | Optional | Radius, chart colors, shadows |
135+
| **5. Semantic** | Do not duplicate | Status and alert tokens inherit from `default.css` |
136+
| **6. Structural** | Branded palettes | Copy the structural override block from `bloom.css` or `cream.css` when needed |
137+
138+
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.
134139

135140
Preview token values at `/custom-page/color` in the Next.js example app.

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

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -176,20 +176,17 @@ const ColorDemoPage = () => {
176176
<ColorSwatch name="chart-5" bgVar="--chart-5" fgVar="--foreground" />
177177
</SwatchSection>
178178

179+
{/* Show author-facing gradient inputs (`base` + `tint`) here.
180+
`start` / `end` are derived from them in the theme CSS. */}
179181
<SwatchSection title="Shell gradient">
180182
<ColorSwatch
181183
name="shell-gradient-base"
182184
bgVar="--shell-gradient-base"
183185
fgVar="--foreground"
184186
/>
185187
<ColorSwatch
186-
name="shell-gradient-start"
187-
bgVar="--shell-gradient-start"
188-
fgVar="--foreground"
189-
/>
190-
<ColorSwatch
191-
name="shell-gradient-end"
192-
bgVar="--shell-gradient-end"
188+
name="shell-gradient-tint"
189+
bgVar="--shell-gradient-tint"
193190
fgVar="--foreground"
194191
/>
195192
</SwatchSection>
@@ -295,7 +292,18 @@ const ColorDemoPage = () => {
295292
padding: "0.75rem",
296293
borderRadius: "var(--radius-md)",
297294
backgroundColor: "var(--shell-gradient-base)",
298-
backgroundImage: `linear-gradient(to bottom, var(--shell-gradient-start), var(--shell-gradient-end))`,
295+
// Keep the preview formula inline so this demo reads the
296+
// same author-facing tokens palette files set: `base` + `tint`.
297+
backgroundImage: `linear-gradient(
298+
to bottom,
299+
color-mix(in srgb, var(--shell-gradient-base) 55%, var(--shell-gradient-tint)) 0%,
300+
color-mix(in srgb, var(--shell-gradient-base) 45%, var(--shell-gradient-tint)) 20%,
301+
color-mix(in srgb, var(--shell-gradient-base) 30%, var(--shell-gradient-tint)) 40%,
302+
color-mix(in srgb, var(--shell-gradient-base) 15%, var(--shell-gradient-tint)) 55%,
303+
color-mix(in srgb, var(--shell-gradient-base) 6%, var(--shell-gradient-tint)) 65%,
304+
var(--shell-gradient-tint) 70%,
305+
var(--shell-gradient-tint) 100%
306+
)`,
299307
border: "1px solid var(--border)",
300308
maxWidth: "14rem",
301309
}}

‎packages/core/src/assets/theme.css‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
/**
22
* Theme system
33
*
4-
* Palettes live in ./themes/*.css. Copy ./_template.css to add a new one.
4+
* `@tailor-platform/app-shell/styles` includes the default palette.
5+
* Import exactly one optional override from `./themes/*.css` after styles
6+
* (for example `@tailor-platform/app-shell/themes/cream`).
57
*
68
* Palette tiers:
79
*
@@ -16,8 +18,8 @@
1618
* Inherited from default.css — do not duplicate in new palettes:
1719
* --ring, --sidebar-*, --status-*, --alert-*.
1820
*
19-
* Mode: `.dark` on <html>. Palette: import one theme file after styles
20-
* (e.g. `@tailor-platform/app-shell/themes/cream`).
21+
* Light/dark mode is controlled separately via `.dark` on <html>.
22+
* Palette selection is by CSS import; there is no runtime palette prop.
2123
*/
2224
@import "./themes/default.css" layer(theme.defaults);
2325

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

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,11 @@
1313
* from `default.css` for neutral palettes, or from `bloom.css` / `cream.css`
1414
* as a starting point for branded shells. Set both modes.
1515
* 5. Optional: section 4 (PALETTE) — radius, chart hues, shadow tint.
16-
* 6. `@import "./themes/{name}.css"` in `theme.css`.
17-
* 7. Set `defaultThemePalette="{name}"` on `<AppShell />` (or let users switch).
16+
* 6. Import `@tailor-platform/app-shell/themes/{name}` after
17+
* `@tailor-platform/app-shell/styles` in the consuming app.
1818
*
1919
* DO NOT SET (inherited from `:root` in default.css):
20-
* --ring, --sidebar-*, --status-*, --alert-*,
21-
* --destructive-foreground formulas in light mode
20+
* --ring, --sidebar-*, --status-*, --alert-*
2221
*
2322
* PREVIEW: `/custom-page/color` in the Next.js example app.
2423
* ═══════════════════════════════════════════════════════════════════════════
@@ -32,7 +31,7 @@
3231
--primary-foreground: /* contrast text on primary */;
3332
--secondary: /* filled secondary actions, badges */;
3433
--secondary-foreground: /* contrast text on secondary */;
35-
--accent: /* menu/sidebar hover & selection — tune by eye, not derived */;
34+
--accent: /* menu/sidebar hover & selection — tune by eye */;
3635
--accent-foreground: /* contrast text on accent */;
3736

3837
/* ── 2. SHELL GRADIENT — optional; omit for flat palettes like default ── */
@@ -112,6 +111,6 @@
112111
}
113112

114113
/*
115-
* Optional: copy the structural overrides block from bloom.css or cream.css
114+
* Optional: copy the structural override block from bloom.css or cream.css
116115
* when using a shell gradient (transparent sidebar, squircle, etc.).
117116
*/

0 commit comments

Comments
 (0)