Table of Contents

• @leaflink/stash-theme
  • Structure
  • CSS layers
  • Usage
  • Token source
  • Documentation references
  • Considerations
    • Default font
    • Breakpoints and Tailwind theme

@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 – chromatic scales at 50–950 (used by the Tailwind @theme); spacing.css, typography.css, shadows.css, sizing.css, motion.css, breakpoints.css – other raw tokens
  • semantic.css – role-based semantic tokens (--stash-color-primary, --stash-color-surface, --stash-color-text, feedback roles) that point at the raw tokens, with light values in :root and dark overrides under .dark
  • data-viz.css – categorical palette for charts (--stash-color-viz-1 … viz-8)
  • 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: maps the primitive families and the semantic roles to Tailwind utilities (bg-primary, text-muted-foreground, and the rest). 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.
• src/tailwind/custom-utilities.css – Custom Tailwind utilities (container, show-empty). Import as @leaflink/stash-theme/custom-utilities, without a layer(...) modifier: Tailwind rejects @utility inside a cascade layer and already emits these into the utilities layer.

CSS layers

Tailwind v4 uses CSS layers (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:

@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);
@import '@leaflink/stash-theme/custom-utilities';
@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 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):

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

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

3. Prefer semantic utilities over raw family utilities. Write bg-primary / text-muted-foreground, not bg-blue-500 / text-ice-700, so a color change happens once in semantic.css. See the Theming guide for the role-to-utility map and per-framework mapping.

Token source

Tokens in this package (src/tokens/*.css) are the single source of truth, in three buckets: primitives (the raw ramp in colors.css), semantic roles (semantic.css, the layer to build UI against), and the data-viz palette (data-viz.css, for charts). 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: @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.
• Tailwind palette: Default Tailwind theme colors remain available; tailwind-theme redefines Stash family names (blue, red, ice, …) to --stash-color-* for steps 50–950 so utilities use one ramp. Use another Tailwind color name (e.g. slate) or arbitrary values when you need stock Tailwind hues beside Stash.
• 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: Semantic tokens ship light and dark values. Light lives in :root; a .dark block on a root element overrides it. Semantic Tailwind utilities flip under .dark on their own — no dark: variant needed. Apps that never add the class render light, unchanged. See the Theming guide.
• 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.