## Table of Contents - [Stash styles](#stash-styles) - [Composing from parts](#composing-from-parts) - [Recommended order](#recommended-order) - [Override behavior](#override-behavior) - [File roles](#file-roles) - [Example: app that composes parts](#example-app-that-composes-parts) # Stash styles Use Stash CSS by composing from parts in the correct order (tokens → tailwind-theme → tailwind-layer → base, etc.). There is no single `theme.css` file. Import the separate files in the order below. ## Composing from parts Import the following in order in your app's main CSS file (e.g. `app.css`). Add optional layers (e.g. `backwards-compat.css`) where noted. ### Recommended order 1. **`tailwindcss/theme.css`** `layer(theme)` 2. **`@leaflink/stash-theme/tokens`** `layer(theme)` — design tokens. **Required before any Stash Tailwind layer.** 3. **`@leaflink/stash-theme/tailwind-theme`** `layer(theme)` — Tailwind mapping for the design tokens. **Required before any Stash Tailwind layer.** 4. **`@leaflink/stash-vue/styles/tailwind-layer.css`** — **Required** when using stash-vue: Stash Tailwind layer (`@source` directives and theme overrides). `.ll-grid` ships in `backwards-compat.css`; `.container` and `.show-empty` are in `@leaflink/stash-theme/custom-utilities` (item 10). 5. **`@leaflink/stash-theme/sofia-font`** `layer(base)` — optional but typical; load font files. 6. **`@leaflink/stash-theme/tailwind-base`** `layer(base)` — **Required** when using stash-vue: Tailwind Preflight + Stash global base. 7. **`@leaflink/stash-vue/styles/components-base.css`** `layer(base)` — **Required** when using stash-vue components: tooltips, transition helpers, `.button-grid`, etc. 8. **`@leaflink/stash-vue/components.css`** `layer(utilities)` — **Required** when using stash-vue components: ships stash component module CSS. Imports into the `utilities` layer so stash module CSS and Tailwind utilities live side by side and arbitrate via normal CSS specificity + source order (see [Override behavior](#override-behavior) below). 9. **`tailwindcss/utilities.css`** `layer(utilities)` `source(none)` 10. **`@leaflink/stash-theme/custom-utilities`** — **no `layer(...)`.** Custom utilities `.container` and `.show-empty` (`@utility` cannot be nested in a cascade layer). Add if your app uses either class. 11. **`@source "./node_modules/@leaflink/stash-vue/dist/*.js";`** — so Tailwind emits the utility classes stash component templates use into your `utilities` layer alongside your own. When integrating **PrimeVue** with `@leaflink/stash-prime`, set `cssLayer.order` in the framework config **and** add the documented fallback `@layer …;` (with comment) before imports in your main CSS, matching that order—see [`packages/prime/README.md`](../../prime/README.md#using-primevue-and-stash-vue-together). For other external libraries, follow their layer guidance. Then your **`@source`** for your app and your app-specific CSS. #### Override behavior Stash module CSS, the Tailwind utilities stash templates use, and your app's Tailwind utilities all live together in the `utilities` layer. Inside one layer, normal CSS rules apply: higher specificity wins, ties go to whichever rule appears last in source order. In practice: - **Apply a Tailwind utility to a stash component** (e.g. ``) — your `.rounded-full` loses no specificity battle against stash's module rule `._button--icon`, and since your CSS loads after stash's, source order picks yours. **Override works.** - **Stash module rules that need to override stash's own template Tailwind** (e.g. TableCell's `.root--density-comfortable:last-of-type:not(.has-actions) { padding-right: 24px }` overriding template `p-3`) — the module selector's higher specificity wins inside the same layer. **Override works.** - **High-specificity stash rules** (multi-class or `:last-of-type:not(...)`) are intentional visual invariants and beat single-class consumer utilities by specificity. Override with Tailwind v4 important syntax (`pr-2!`) or a more specific selector when needed. Optional pieces you may add where they fit your stack: - **`@leaflink/stash-vue/styles/backwards-compat.css`** — legacy variables and migrated component/override styles. Use if your app still relies on them. ### File roles | File | Purpose | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **tailwind-layer.css** | **Canonical Stash Tailwind layer entrypoint.** Requires `@leaflink/stash-theme/tokens` and `@leaflink/stash-theme/tailwind-theme` first. Use this when composing parts. | | **tailwind/index.css** | Internal composition of `sources.css`, and `overrides.css`. Prefer importing `tailwind-layer.css` from apps and docs. | | **tailwind/sources.css** | Only `@source` directives so Tailwind includes Stash dynamic class names. | | **tailwind/overrides.css** | `:root` vars and `@theme` overrides (e.g. `--font-sans`, legacy `--font-sofia`). Requires tokens + tailwind-theme first. | | **`@leaflink/stash-theme/tailwind-reset`** | Tailwind Preflight + Stash reset defaults. **Use before `tailwind-base`**. | | **`@leaflink/stash-theme/tailwind-base`** | Stash global base styles. **Use with stash-vue** (peer: `tailwindcss` ^4.2). | | **components-base.css** | Vue-specific utilities (tooltips, animations, transitions, `.button-grid`). **Pair with `tailwind-base` whenever you use stash-vue components.** | | **backwards-compat.css** | Legacy variables, the `.ll-grid` layout class, and migrated styles. Optional. | | **`@leaflink/stash-theme/custom-utilities`** | `.container` and `.show-empty`. **Import without a `layer(...)` modifier** (`@utility` cannot be nested). | The default sans is **Sofia**, resolved via `--stash-font-sans` in the theme tokens. Import **`@leaflink/stash-theme/sofia-font`** when composing parts so the font files are available. ### Example: app that composes parts This example uses the **default** font stack (Sofia). Treat this snippet as the **canonical stash-vue theme stack**; other docs (including the Tailwind v4 migration guide and VitePress `main.css`) should follow the same import order. ```css @layer theme, reset, vendor, base, components, utilities; @import 'tailwindcss/theme.css' layer(theme); @import '@leaflink/stash-theme/tokens' layer(theme); @import '@leaflink/stash-theme/tailwind-theme' layer(theme); @import '@leaflink/stash-vue/styles/tailwind-layer.css'; @import '@leaflink/stash-theme/tailwind-reset' layer(reset); @import '@leaflink/stash-theme/sofia-font' layer(base); /* load Sofia font files */ @import '@leaflink/stash-theme/tailwind-base' layer(base); @import '@leaflink/stash-vue/styles/components-base.css' layer(base); @import '@leaflink/stash-vue/styles/backwards-compat.css' layer(base); /* optional */ @import '@leaflink/stash-vue/components.css' layer(utilities); @import 'tailwindcss/utilities.css' layer(utilities) source(none); @import '@leaflink/stash-theme/custom-utilities'; @source "../../src/**/*.{vue,ts,js}"; @source "../../node_modules/@leaflink/stash-vue/dist/*.js"; /* your app CSS */ ``` > **Migrating from a previous version:** if you previously imported components.css with `layer(components)`, switch it > to `layer(utilities)` (see [Override behavior](#override-behavior)). Keep your existing > `@source "../../node_modules/@leaflink/stash-vue/dist/*.js";` directive — Tailwind needs it to emit the classes stash > component templates use. If you omit `tailwind-layer.css`, you must still load **`@leaflink/stash-theme/tokens`** and **`@leaflink/stash-theme/tailwind-theme`** before any Stash CSS that uses theme tokens (e.g. `gap-x-gutter`, `theme(--breakpoint-lg)`), or Tailwind will error on unknown utilities.