@vellira-ui/tokens

Shared design tokens for Vellira.

This package is the single source of truth for primitive colors, semantic tokens, component tokens, typography, spacing, radius, shadows, and z-index values used by both the React and React Native packages.

Installation

pnpm add @vellira-ui/tokens

Features

• Shared design tokens
• Semantic color system
• Renderer-neutral theme objects
• Component-level tokens
• Generated CSS variables
• TypeScript-first API

Usage

import {
  darkTheme,
  highContrastTheme,
  lightTheme,
  theme,
} from '@vellira-ui/tokens';

theme.semantic.surface.default;
theme.semantic.text.primary;
theme.semantic.border.default;
theme.semantic.status.success.fg;

theme.components.button.primary.solid.default.bg;
theme.components.input.default.bg;

theme.tokens.typography.family.regular;
theme.tokens.spacing[4];
theme.tokens.radius.md;

lightTheme.name;
darkTheme.name;
highContrastTheme.name;

Semantic Tokens

The package provides semantic groups that describe intent instead of coupling components to raw palette values.

Current semantic groups include:

• action
• border
• control
• divider
• focus
• icons
• menu
• navigation
• overlay
• shadow
• skeleton
• status
• surface
• text

Example:

theme.semantic.surface.default;
theme.semantic.surface.elevated;

theme.semantic.text.primary;
theme.semantic.text.secondary;

theme.semantic.border.default;

theme.semantic.status.success.fg;
theme.semantic.status.error.fg;

Using semantic tokens instead of raw palette values keeps component styling consistent across renderers and themes.

Component Tokens

Component tokens define renderer-neutral values for component states and surfaces.

theme.components.button.primary.solid.default.bg;
theme.components.input.focus.border;
theme.components.dropdown.content.bg;
theme.components.popover.content.bg;
theme.components.modal.content.bg;
theme.components.tooltip.content.bg;

Color-like component tokens may use either colors or the literal transparent when the intended rendered value is transparent.

CSS Variables

Generated CSS variables are available for web projects:

import '@vellira-ui/tokens/css';

Examples:

--color-mono-0
--surface-default
--text-primary
--border-default
--button-primary-solid-default-bg

Documentation

• Design Tokens
• Theme Architecture
• React
• React Native

Development

Build the package:

pnpm --filter @vellira-ui/tokens build

Token path unions, CSS variable name unions, and theme structure types are generated from the token source files:

pnpm --filter @vellira-ui/tokens generate:types

Verify that generated token types are up to date:

pnpm --filter @vellira-ui/tokens generate:types:check

Principles

• Semantic tokens over hardcoded colors
• Shared across React and React Native
• Stable public API
• Predictable naming
• Theme-ready architecture