<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## 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)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# 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, which
   includes `@source` directives, theme overrides, and shared layout utilities (`.ll-grid`, `.container`,
   `.show-empty`).
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. **`@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.

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. `<Button class="rounded-full" />`) — 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`, `overrides.css`, and `tailwind/component-utilities.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.                                                |
| **tailwind/component-utilities.css**       | `.ll-grid`, `.container`, `.show-empty`. Requires theme layer.                                                                                                          |
| **`@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 and migrated styles. Optional.                                                                                                                         |

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, 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);

@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.
