@vinyasa/tokens 1.0.15 → 1.0.16

package/README.md

@@ -0,0 +1,119 @@
+# @vinyasa/tokens
+
+The shared design-token and theming foundation for `@vinyasa/*` components: a color/spacing/typography/motion contract plus a `VinyasaProvider` that resolves and injects real values at runtime.
+
+## Installation
+
+```bash
+pnpm add @vinyasa/tokens react react-dom
+```
+
+## Setup
+
+Wrap your app once, near the root:
+
+```tsx
+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
+
+Values are organized in three tiers:
+
+1. **Primitives** (`primitives.ts`) — raw, numeric-keyed scales with no meaning attached: `gray[900]`, `blue[500]`, `space[3]`.
+2. **Semantic contract** (`themeContract`, exported from this package) — a flat, brand-role naming tier: `primary`/`onPrimary`, `secondary`/`onSecondary`, `tertiary`/`onTertiary`, `error`/`onError`, plus `focus`, spacing (`space1`–`space6`), radii, font size/weight, line height, motion timing, and `borderWidthThin`. This is what a component's own `.css.ts` file imports and references — never the primitives directly.
+3. **Runtime theme** (`defaultTheme`, `createTheme`, `VinyasaProvider`) — the actual values, injected as CSS custom properties at render time (via `@vanilla-extract/dynamic`), not baked into a static stylesheet. This is what makes overriding a value a runtime prop, not a rebuild.
+
+### Overriding values
+
+Pass a partial theme — only the keys you override change, everything else keeps its default:
+
+```tsx
+<VinyasaProvider theme={{ primary: '#7c3aed' }}>
+	<YourApp />
+</VinyasaProvider>
+```
+
+You can also build a full custom theme ahead of time with `createTheme`:
+
+```tsx
+import { createTheme, VinyasaProvider } from '@vinyasa/tokens';
+
+const brandTheme = createTheme({ primary: '#7c3aed', onPrimary: '#ffffff' });
+
+<VinyasaProvider theme={brandTheme}>
+	<YourApp />
+</VinyasaProvider>;
+```
+
+Providers can be nested for scoped overrides — an inner `VinyasaProvider` only affects the subtree it wraps.
+
+### Reading the theme programmatically
+
+```tsx
+import { useVinyasaTheme } from '@vinyasa/tokens';
+
+function Component() {
+	const theme = useVinyasaTheme();
+	return <span style={{ color: theme.primary }}>...</span>;
+}
+```
+
+### `colorScheme` and `contrast`
+
+```tsx
+<VinyasaProvider colorScheme="light" contrast="normal">
+```
+
+Only `light`/`normal` values are authored today. The registry these resolve from (`resolveBaseTheme`) is structured so adding `dark` or `high`-contrast values later is purely additive — no changes to the contract, the provider, or any component that consumes it. Requesting an unshipped combination falls back to `light`/`normal` with a console warning in development.
+
+## Consuming the contract in your own component
+
+This is the pattern every `@vinyasa/*` component follows — reference `themeContract`, never hardcode a value:
+
+```ts
+// 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.
+
+## API
+
+| Export                                                            | Description                                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `VinyasaProvider`                                                 | React component. Props: `theme?`, `colorScheme?`, `contrast?`, `children`.            |
+| `useVinyasaTheme()`                                               | Hook returning the currently resolved `VinyasaTheme` object.                          |
+| `themeContract`                                                   | The token contract — import as `vars` in a component's `.css.ts` file.                |
+| `defaultTheme`                                                    | The default (light/normal) theme values object.                                       |
+| `createTheme(overrides)`                                          | Merges a partial theme onto `defaultTheme`, returning a full `VinyasaTheme`.          |
+| `resolveBaseTheme(colorScheme, contrast)`                         | Looks up the base theme for a scheme/contrast pair, with a dev-mode fallback warning. |
+| `VinyasaTheme`, `ColorScheme`, `Contrast`, `VinyasaProviderProps` | Types.                                                                                |
+
+## Development
+
+From the repository root:
+
+```bash
+pnpm --filter @vinyasa/tokens build
+pnpm --filter @vinyasa/tokens test
+pnpm --filter @vinyasa/tokens lint
+```

package/dist/cjs/index.cjs

@@ -54,6 +54,7 @@ var themeContract = {
     radiusSm: 'var(--vinyasa-radius-sm)',
     radiusMd: 'var(--vinyasa-radius-md)',
     radiusFull: 'var(--vinyasa-radius-full)',
+    borderWidthThin: 'var(--vinyasa-border-width-thin)',
     fontSizeSm: 'var(--vinyasa-font-size-sm)',
     fontSizeMd: 'var(--vinyasa-font-size-md)',
     fontWeightRegular: 'var(--vinyasa-font-weight-regular)',
@@ -100,6 +101,9 @@ const radius = {
     md: '0.5rem',
     full: '9999px'
 };
+const borderWidth = {
+    thin: '1px'
+};
 const fontSize = {
     sm: '0.875rem',
     md: '1rem'
@@ -158,6 +162,7 @@ const defaultTheme = {
     radiusSm: radius.sm,
     radiusMd: radius.md,
     radiusFull: radius.full,
+    borderWidthThin: borderWidth.thin,
     fontSizeSm: fontSize.sm,
     fontSizeMd: fontSize.md,
     fontWeightRegular: fontWeight.regular,

package/dist/esm/contract.css.d.ts

@@ -17,6 +17,7 @@ export declare const themeContract: {
     radiusSm: `var(--${string})`;
     radiusMd: `var(--${string})`;
     radiusFull: `var(--${string})`;
+    borderWidthThin: `var(--${string})`;
     fontSizeSm: `var(--${string})`;
     fontSizeMd: `var(--${string})`;
     fontWeightRegular: `var(--${string})`;

package/dist/esm/index.js

@@ -20,6 +20,7 @@ var themeContract = {
     radiusSm: 'var(--vinyasa-radius-sm)',
     radiusMd: 'var(--vinyasa-radius-md)',
     radiusFull: 'var(--vinyasa-radius-full)',
+    borderWidthThin: 'var(--vinyasa-border-width-thin)',
     fontSizeSm: 'var(--vinyasa-font-size-sm)',
     fontSizeMd: 'var(--vinyasa-font-size-md)',
     fontWeightRegular: 'var(--vinyasa-font-weight-regular)',
@@ -66,6 +67,9 @@ const radius = {
     md: '0.5rem',
     full: '9999px'
 };
+const borderWidth = {
+    thin: '1px'
+};
 const fontSize = {
     sm: '0.875rem',
     md: '1rem'
@@ -101,6 +105,7 @@ const defaultTheme = {
     radiusSm: radius.sm,
     radiusMd: radius.md,
     radiusFull: radius.full,
+    borderWidthThin: borderWidth.thin,
     fontSizeSm: fontSize.sm,
     fontSizeMd: fontSize.md,
     fontWeightRegular: fontWeight.regular,

package/dist/esm/primitives.d.ts

@@ -35,6 +35,9 @@ export declare const radius: {
     readonly md: "0.5rem";
     readonly full: "9999px";
 };
+export declare const borderWidth: {
+    readonly thin: "1px";
+};
 export declare const fontSize: {
     readonly sm: "0.875rem";
     readonly md: "1rem";

package/dist/esm/theme.d.ts

@@ -17,6 +17,7 @@ export interface VinyasaTheme {
     radiusSm: string;
     radiusMd: string;
     radiusFull: string;
+    borderWidthThin: string;
     fontSizeSm: string;
     fontSizeMd: string;
     fontWeightRegular: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vinyasa/tokens",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "private": false,
   "type": "module",
   "sideEffects": [