<!-- 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)
    - [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(components)` — when using pre-built component CSS from the package
   build.
9. **`tailwindcss/utilities.css`** `layer(utilities)` `source(none)`

For other external libraries, follow their layer guidance. Then your **`@source`** for app (and optionally Stash dist)
and your app-specific CSS.

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(components);
@import 'tailwindcss/utilities.css' layer(utilities) source(none);

@source "../../src/**/*.{vue,ts,js}";
@source "../../node_modules/@leaflink/stash-vue/dist/*.js";

/* your app CSS */
```

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.
