npm package: @leaflink/stash-theme
Description: Stash design tokens, fonts, and Tailwind theme adapter
Latest version: 56.0.0

<!-- 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

- [@leaflink/stash-theme](#leaflinkstash-theme)
  - [Structure](#structure)
  - [CSS layers](#css-layers)
  - [Usage](#usage)
  - [Token source](#token-source)
  - [Documentation references](#documentation-references)
  - [Considerations](#considerations)
    - [Default font](#default-font)
    - [Breakpoints and Tailwind theme](#breakpoints-and-tailwind-theme)

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

# @leaflink/stash-theme

Design tokens and shared Tailwind theme assets for the Stash design system. Tokens are the single source of truth used
by framework adapters so Vue, React, and framework-agnostic UIs stay consistent.

## Structure

All theme assets live under `src/`. Package exports point into these paths.

- **`src/tokens/`** – Design tokens as CSS custom properties (`--stash-*`). Use these directly or via the Tailwind
  theme.
  - `colors.css`, `spacing.css`, `typography.css`, `shadows.css`, `sizing.css`, `motion.css`, `breakpoints.css` – raw
    tokens
  - `semantic.css` – semantic names (e.g. `--stash-color-primary`, `--stash-color-surface-ground`) that point at the raw
    tokens
  - `index.css` – imports all token files. Import as `@leaflink/stash-theme/tokens`.
- **`src/fonts/sofia/sofia-font.css`** – `@font-face` for Sofia Pro. Import as `@leaflink/stash-theme/sofia-font` when
  you need the font files loaded.
- **`src/adapters/tailwind/theme.css`** – Tailwind v4 theme: full `@theme` mapping from Stash tokens. Consumed by
  `packages/vue` and any app using Tailwind v4. Import as `@leaflink/stash-theme/tailwind-theme`. The adapter re-exports
  `src/tailwind/theme.css` so the public entry stays stable if the implementation path changes.

## CSS layers

Tailwind v4 uses [CSS layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) (default order: `theme`, `base`,
`components`, `utilities`). When using this package, import tokens and the Tailwind theme in the `theme` layer so all
theme variables are available before base/components/utilities. Example:

```css
@import 'tailwindcss/theme.css' layer(theme);
@import '@leaflink/stash-theme/tokens' layer(theme);
@import '@leaflink/stash-theme/tailwind-theme' layer(theme);
@import '@leaflink/stash-theme/tailwind-base' layer(base);
@import 'tailwindcss/utilities.css' layer(utilities) source(none);
@source '../../src/**/*.{vue,ts,js}';
```

This snippet is for apps that use only the theme package with Tailwind (no Stash Vue components). For the full stack,
including `@leaflink/stash-vue/styles/tailwind-layer.css`, **`@leaflink/stash-theme/tailwind-base`**,
`components-base.css`, and `components.css`, see the
[Tailwind v4 Migration Guide](../../docs/architecture/TAILWIND_V4_MIGRATION.md) and the Stash Vue README.

## Usage

**`@leaflink/stash-theme/tailwind-base`:** Depends on **`tailwindcss` ^4.2.0** (declared as a peer dependency). That
entry imports `tailwindcss/preflight.css`; your app must install compatible `tailwindcss` and `@tailwindcss/postcss` so
the bundler can resolve the `tailwindcss` package from `@leaflink/stash-theme` (pnpm strict layouts require this).

1. **Tokens only** (e.g. custom CSS or build pipeline):

   ```css
   @import '@leaflink/stash-theme/tokens';
   ```

   Then use `var(--stash-color-ice-700)`, `var(--stash-color-primary)`, etc.

2. **Tailwind v4** (when the theme is fully wired): import Tailwind then our theme in the same layer so our `@theme`
   overrides apply. See [Tailwind theme docs](https://tailwindcss.com/docs/theme).

   ```css
   @import 'tailwindcss';
   @import '@leaflink/stash-theme/tokens' layer(theme);
   @import '@leaflink/stash-theme/tailwind-theme' layer(theme);
   ```

## Token source

Tokens in this package (`src/tokens/*.css`) are the single source of truth. The Tailwind theme
(`src/adapters/tailwind/theme.css`) consumes them via `var(--stash-*)`. When updating the design system, change tokens
here first; `packages/vue` and consuming apps import `@leaflink/stash-theme/tokens` then
`@leaflink/stash-theme/tailwind-theme`.

## Documentation references

- **Tailwind CSS v4** – [Theme variables](https://tailwindcss.com/docs/theme): `@theme` directive, namespaces
  (`--color-*`, `--breakpoint-*`, `--font-*`, `--shadow-*`, etc.), default layer order
  `theme, base, components, utilities`.

## Considerations

- **Legacy:** `packages/vue/tailwind-base.ts` remains for Tailwind v3; the theme package is the source of truth for
  Tailwind v4. Docs use v4 and the theme package.
- **Legacy color aliases:** `src/tokens/colors.css` exposes aliases like `--color-blue-hover` for backwards
  compatibility. Consumer apps (and Stash components) may use them; treat them as part of the public theme API. Prefer
  semantic tokens (`--stash-*`) for new code, but do not remove these aliases without a deprecation path for consumers.
- **Dark mode:** Tokens are light-only; consumers can introduce dark-mode tokens or presets on top of this package if
  needed.
- **Versioning:** When publishing, `@leaflink/stash-theme` can be versioned with `@leaflink/stash-vue` (same release) or
  independently if other products adopt it without Vue.
- **Docs `public/fonts`:** The docs app may have a `public/fonts` symlink or copy (e.g. to `packages/vue/assets/fonts`)
  for assets served at build time. Sofia is provided via `@leaflink/stash-theme/sofia-font`; the symlink is only needed
  for other fonts (e.g. Menlo) if referenced by URL in docs.

### Default font

The default sans font is **Sofia**. The default stack resolves `--font-sans` to `--stash-font-sans`, which points at
Sofia via the typography tokens. To load the font files, import `@leaflink/stash-theme/sofia-font` once in your app’s
base CSS before applying theme styles.

`sofia-font.css` references font files with `url('@leaflink/stash-theme/fonts/sofia/…')` so Vite (and similar bundlers)
resolve them through `package.json` exports and emit correct asset URLs. If you see 404s to paths under
`/node_modules/.../src/fonts/sofia/`, ensure your build processes CSS `url()` from dependencies (Vite does by default).

### Breakpoints and Tailwind theme

Tailwind v4 breakpoints are defined in `src/adapters/tailwind/theme.css` using literal values (e.g.
`--breakpoint-lg: 961px`) because CSS variables cannot be used inside media queries. The same breakpoint values also
exist in `src/tokens/breakpoints.css` for non-Tailwind consumers. **When changing breakpoints, update both files in
lockstep** so token consumers and Tailwind stay in sync.