@vinyasa/tokens

The shared design-token and theming foundation for @vinyasa/* components: color, spacing, radius, border, typography, motion, focus rings, opacity, shadows, elevation, blur, and z-index tokens, plus static breakpoint/grid values and a VinyasaProvider that resolves and injects the themeable tokens at runtime.

For a live, click-to-copy reference of every single token value, run Storybook and open Foundations (pnpm storybook, then Colors / Elevation / Typography / Spacing / Brand / Layout). This README covers setup, integration, and the full prop/API surface instead of re-listing every value.

Installation

pnpm add @vinyasa/tokens react react-dom

Setup

Wrap your app once, near the root:

import { VinyasaProvider } from '@vinyasa/tokens';

function App() {
	return (
		<VinyasaProvider>
			<YourApp />
		</VinyasaProvider>
	);
}

VinyasaProvider resolves a theme and injects it as CSS custom properties on a display: contents wrapper element (no extra layout box), scoped to everything rendered inside it. Any @vinyasa/* component rendered under the provider picks up those values automatically — there's no separate stylesheet to import.

How theming works

There's no "primitives" tier — every file owns its own literal values directly, organized by what actually varies together:

1. Structural scales (spacing.ts, radius.ts, border.ts, shadow.ts) — plain numeric/length scales that never change per theme or brand: the same space1–space8, radiusXs–radiusFull, borderWidthThin/Thick, and shadow shape everywhere. themes/base.ts pulls these in, adds typography/motion/opacity/blur/z-index (owned directly, since nothing else needs them), and defines the full VinyasaTheme interface every theme must satisfy.
2. Scheme (themes/light.ts, themes/dark.ts) — the neutral gray ramp, surface, text, borders, shadows, and the info/success/warning/error semantic colors. A true neutral, not tinted toward any brand — switching brand never changes how "the page" looks, only the accent.
3. Brand (brands.ts) — just the accent: primary/onPrimary/focus/tertiary/onTertiary, tuned separately for light and dark grounds and for normal/high contrast. duskBrand (default), sunriseBrand, and yellowBrand ship today; adding a new one is a new entry in brands.ts plus one line in VinyasaProvider's internal lookup — no other file changes.
4. Semantic contract (themeContract, exported as vars) — the flat set of CSS custom property names every @vinyasa/* component's own .css.ts file reads. Components never reach past this into scheme or brand files directly.
5. Runtime theme — VinyasaProvider merges scheme + brand + density + your own theme override into one VinyasaTheme object and injects it as CSS custom properties at render time (via @vanilla-extract/dynamic), not baked into a static stylesheet. Overriding a value is a runtime prop, not a rebuild.

breakpoints and grid (from layout.ts) are the one exception to all of this — they're exported as plain static values, not part of themeContract. CSS custom properties can't appear inside @media query conditions (@media (min-width: var(--x)) is invalid in every browser), so responsive breakpoints can never be runtime-themed the way colors or spacing can. Consume them as literals directly in your own component's build-time @media blocks.

VinyasaProvider props

| Prop | Type | Default | Description | | ------------- | ------------------------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | children | ReactNode | — | Required. | | colorScheme | 'light' \| 'dark' | 'light' | Which scheme's neutrals/surface/text/borders/shadows/status colors to use. | | brand | 'dusk' \| 'sunrise' \| 'yellow' | 'dusk' | Which accent (primary/onPrimary/focus/tertiary/onTertiary) to layer on top. | | contrast | 'normal' \| 'high' | 'normal' | Swaps in WCAG-AAA-verified (7:1) shades for the tokens that need it at high contrast. | | density | 'compact' \| 'comfortable' \| 'spacious' | 'comfortable' | Rescales space1–space8 only — nothing else changes. | | theme | ThemeOverride | undefined | { light?: { normal?, high? }, dark?: { normal?, high? } } of Partial<VinyasaTheme> — scoped to the active colorScheme/contrast, see below. |

Resolution order (each step merges onto the previous, right-most wins): resolveBaseTheme(colorScheme, contrast) → brand accent for (brand, colorScheme, contrast) → density spacing overlay → the theme[colorScheme][contrast] branch of your theme prop, if you supplied one.

colorScheme

<VinyasaProvider colorScheme="dark">
	<YourApp />
</VinyasaProvider>

brand

Independent of colorScheme — any brand works with either scheme:

<VinyasaProvider brand="sunrise">
	<YourApp />
</VinyasaProvider>

<VinyasaProvider colorScheme="dark" brand="sunrise">
	<YourApp />
</VinyasaProvider>

contrast

<VinyasaProvider contrast="high">
	<YourApp />
</VinyasaProvider>

density

<VinyasaProvider density="compact">
	<YourApp />
</VinyasaProvider>

Combining props

All four combine freely — e.g. a dark, high-contrast, compact, sunrise-branded app:

<VinyasaProvider colorScheme="dark" brand="sunrise" contrast="high" density="compact">
	<YourApp />
</VinyasaProvider>

Nesting providers

An inner VinyasaProvider only affects the subtree it wraps — useful for a themed preview panel, an embedded widget, or a settings page previewing a different mode without affecting the rest of the app:

<VinyasaProvider>
	<YourApp />
	<VinyasaProvider colorScheme="dark">
		<EmbeddedPreview />
	</VinyasaProvider>
</VinyasaProvider>

Overriding individual values

theme is scoped by colorScheme and contrast — an override written under light is only ever applied when colorScheme="light" is also active, and never leaks into dark (or vice versa). Every level is optional; only fill in the branches you actually need:

<VinyasaProvider
	theme={{
		light: { normal: { primary: '#7c3aed' } },
		dark: { normal: { primary: '#a78bfa' } },
	}}
>
	<YourApp />
</VinyasaProvider>

Only overriding one scheme is fine — the other keeps its normal resolved value:

<VinyasaProvider theme={{ light: { normal: { primary: '#7c3aed' } } }}>
	<YourApp />
</VinyasaProvider>

To scope an override to one brand (rather than one colorScheme), pick the override object yourself, the same way you already pick which brand to pass — there's no separate brand axis in theme itself, since you already hold that value directly:

const sunriseOverride = { light: { normal: { primary: '#ff5a2b' } } };

<VinyasaProvider brand={brand} theme={brand === 'sunrise' ? sunriseOverride : undefined}>
	<YourApp />
</VinyasaProvider>;

createTheme is a separate helper — it builds a complete, standalone VinyasaTheme object (based on lightTheme), not a theme prop value. Use it when you need a full theme object on its own (e.g. to pass to ThemeContext directly), not for scoped overrides:

import { createTheme } from '@vinyasa/tokens';

const customTheme = createTheme({ primary: '#7c3aed', onPrimary: '#ffffff' });

Reading the theme programmatically

import { useVinyasaTheme } from '@vinyasa/tokens';

function Component() {
	const theme = useVinyasaTheme();
	return <span style={{ color: theme.primary }}>...</span>;
}

Reads the resolved VinyasaTheme object from React context — the same values injected as CSS custom properties, available as plain strings for cases (canvas, SVG, inline style math) that can't take a var(...).

Consuming the contract in your own component

This is the pattern every @vinyasa/* component follows — reference themeContract, never hardcode a value:

// YourComponent.css.ts
import { style } from '@vanilla-extract/css';
import { themeContract as vars } from '@vinyasa/tokens';

export const root = style({
	backgroundColor: vars.primary,
	color: vars.onPrimary,
	padding: `${vars.space3} ${vars.space4}`,
	borderRadius: vars.radiusFull,
});

pnpm create:package <name> scaffolds new component packages wired to this contract by default.

Wiring up the component's own ref

Any component that reads themeContract values on its own rendered node should use useThemedRef instead of a plain useRef/forwardRef ref — it merges the caller's own ref with an internal one used to dev-warn if the node ever renders outside a VinyasaProvider (e.g. via a portal that escapes its DOM subtree):

import { useThemedRef } from '@vinyasa/tokens';
import { forwardRef, type ComponentPropsWithoutRef } from 'react';

const YourComponent = forwardRef<HTMLDivElement, ComponentPropsWithoutRef<'div'>>((props, ref) => {
	const themedRef = useThemedRef(ref);
	return <div ref={themedRef} {...props} />;
});

Focus rings

focusRingStyle(vars) returns the shared focus-visible style (a soft box-shadow halo, not a hard outline — outlines don't reliably follow border-radius across browsers) to spread into a component's own :focus-visible selector:

import { recipe } from '@vanilla-extract/recipes';
import { focusRingStyle, themeContract as vars } from '@vinyasa/tokens';

export const button = recipe({
	base: {
		selectors: {
			'&:focus-visible': focusRingStyle(vars),
		},
	},
});

Breakpoints & grid

Static, not themeable — import and use directly in your own build-time styles:

import { style } from '@vanilla-extract/css';
import { breakpoints } from '@vinyasa/tokens';

export const responsive = style({
	'@media': {
		[`(min-width: ${breakpoints.md})`]: {
			flexDirection: 'row',
		},
	},
});

Full API reference

| Export | Description | | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | VinyasaProvider | React component. Props: theme?, colorScheme?, brand?, contrast?, density?, children. | | useVinyasaTheme() | Hook returning the currently resolved VinyasaTheme object. | | useThemedRef(ref?) | Hook merging a caller's ref with a dev-mode "rendered outside a provider" check. | | useAssertVinyasaProvider(ref) | Lower-level dev-mode check useThemedRef builds on — rarely used directly. | | themeContract | The token contract — import as vars in a component's .css.ts file. | | focusRingStyle(vars) | Returns the shared :focus-visible style object. | | lightTheme, darkTheme | The normal-contrast, default-brand values object for each scheme. | | lightHighContrastTheme, darkHighContrastTheme | The high-contrast, default-brand values object for each scheme. | | createTheme(overrides) | Merges a partial theme onto lightTheme, returning a full VinyasaTheme. | | resolveBaseTheme(colorScheme, contrast) | Looks up the scheme theme for a colorScheme/contrast pair, with a dev-mode fallback warning. | | resolveDensitySpacing(density) | Looks up the space1–space8 overlay for a density, with a dev-mode fallback warning. | | duskBrand, sunriseBrand, yellowBrand | The brand accent objects, each { light: { normal, high }, dark: { normal, high } }. | | breakpoints, grid | Static layout values (not themeable — see above). From layout.ts. | | VinyasaTheme, ColorScheme, Contrast, Density, BrandName, Brand, BrandAccent, ThemeOverride, VinyasaProviderProps | Types. |

Development

From the repository root:

pnpm --filter @vinyasa/tokens build
pnpm --filter @vinyasa/tokens test
pnpm --filter @vinyasa/tokens lint
pnpm --filter @vinyasa/tokens typecheck