Design Tokens

Cosella’s design system is built on a comprehensive token system using Tailwind v4 @theme {} blocks. All tokens are defined as CSS custom properties and exposed as Tailwind utility classes.

Installation

pnpm add @cosella/tokens

Usage

CSS Import

@import "tailwindcss";
@import "@cosella/tokens/theme.css";
@import "@cosella/tokens/components.css";

JavaScript Import

import { brand, colorVar, duration, ease, zIndex, radius } from '@cosella/tokens';
import { ThemeProvider, useTheme } from '@cosella/tokens';

Tailwind Utility Classes

All tokens are available as Tailwind classes:

<div className="bg-brand-500 text-white rounded-lg p-4">
  Brand background with white text
</div>

<div className="bg-bg-raised border-border text-text-primary">
  Card-like surface
</div>

<div className="text-success font-medium">
  Success text
</div>

Color System

Brand Colors (Forest Green)

Primary brand palette with 11 shades:

Token	Tailwind Class	Light Mode	Dark Mode
`brand-50`	`bg-brand-50`	oklch(97% 0.02 145)	oklch(97% 0.02 145)
`brand-100`	`bg-brand-100`	oklch(93% 0.04 145)	oklch(93% 0.04 145)
`brand-200`	`bg-brand-200`	oklch(87% 0.07 145)	oklch(87% 0.07 145)
`brand-300`	`bg-brand-300`	oklch(78% 0.11 145)	oklch(78% 0.11 145)
`brand-400`	`bg-brand-400`	oklch(67% 0.15 145)	oklch(67% 0.15 145)
`brand-500`	`bg-brand-500`	oklch(58% 0.12 148)	oklch(58% 0.12 148)
`brand-600`	`bg-brand-600`	oklch(48% 0.09 148)	oklch(48% 0.09 148)
`brand-700`	`bg-brand-700`	oklch(40% 0.07 145)	oklch(40% 0.07 145)
`brand-800`	`bg-brand-800`	hsl(128 14% 22%)	hsl(128 14% 22%)
`brand-900`	`bg-brand-900`	oklch(23% 0.03 145)	oklch(23% 0.03 145)
`brand-950`	`bg-brand-950`	oklch(15% 0.02 145)	oklch(15% 0.02 145)

Neutral Colors (Cool Blue-Gray)

Token	Tailwind Class	Value
`neutral-50`	`bg-neutral-50`	oklch(98% 0.003 250)
`neutral-100`	`bg-neutral-100`	oklch(95% 0.005 250)
`neutral-200`	`bg-neutral-200`	hsl(214 32% 91%)
`neutral-300`	`bg-neutral-300`	oklch(83% 0.012 250)
`neutral-400`	`bg-neutral-400`	oklch(70% 0.012 250)
`neutral-500`	`bg-neutral-500`	oklch(58% 0.012 250)
`neutral-600`	`bg-neutral-600`	oklch(47% 0.01 250)
`neutral-700`	`bg-neutral-700`	oklch(37% 0.008 250)
`neutral-800`	`bg-neutral-800`	oklch(27% 0.006 265)
`neutral-900`	`bg-neutral-900`	oklch(17% 0.01 265)

Semantic Colors

Context-aware colors that adapt to light/dark mode:

Token	Tailwind Class	Light Mode	Dark Mode
`bg-base`	`bg-bg-base`	green-mist	oklch(17% 0.01 265)
`bg-raised`	`bg-bg-raised`	white	oklch(20% 0.01 265)
`bg-subtle`	`bg-bg-subtle`	green-mist	oklch(23% 0.01 265)
`text-primary`	`text-text-primary`	black	oklch(94% 0.008 240)
`text-secondary`	`text-text-secondary`	brand-800	oklch(94% 0.008 240)
`text-muted`	`text-text-muted`	oklch(60% 0.02 250)	oklch(60% 0.015 250)
`primary`	`bg-primary`	brand-800	oklch(58% 0.12 148)
`border`	`border-border`	neutral-200	oklch(17% 0.01 265)

Status Colors

Token	Tailwind Class	Value
`success`	`bg-success`	oklch(44% 0.13 145)
`warning`	`bg-warning`	oklch(65% 0.18 80)
`danger`	`bg-danger`	oklch(53% 0.22 20)
`info`	`bg-info`	oklch(55% 0.16 220)

Badge Colors

Token	Tailwind Class (bg)	Tailwind Class (text)
`badge-blue`	`bg-badge-blue-bg`	`text-badge-blue-text`
`badge-green`	`bg-badge-green-bg`	`text-badge-green-text`
`badge-red`	`bg-badge-red-bg`	`text-badge-red-text`
`badge-amber`	`bg-badge-amber-bg`	`text-badge-amber-text`
`badge-purple`	`bg-badge-purple-bg`	`text-badge-purple-text`

Typography

Font Families

--font-sans: 'Epilogue', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', ui-monospace, monospace;

className="font-sans"  {/* Epilogue */}
className="font-mono"  {/* JetBrains Mono */}

Font Sizes

Token	Tailwind Class	Size	Line Height
`text-xs`	`text-xs`	0.75rem (12px)	1rem
`text-sm`	`text-sm`	0.875rem (14px)	1.25rem
`text-base`	`text-base`	1rem (16px)	1.5rem
`text-lg`	`text-lg`	1.125rem (18px)	1.75rem
`text-xl`	`text-xl`	1.25rem (20px)	1.75rem
`text-2xl`	`text-2xl`	1.5rem (24px)	2rem
`text-3xl`	`text-3xl`	1.875rem (30px)	2.25rem
`text-4xl`	`text-4xl`	2.25rem (36px)	2.5rem

Spacing

Standard Tailwind spacing scale plus extras:

Token	Tailwind Class	Value
`spacing-1`	`p-1` / `m-1`	0.25rem (4px)
`spacing-2`	`p-2` / `m-2`	0.5rem (8px)
`spacing-4`	`p-4` / `m-4`	1rem (16px)
`spacing-6`	`p-6` / `m-6`	1.5rem (24px)
`spacing-8`	`p-8` / `m-8`	2rem (32px)
`spacing-12`	`p-12` / `m-12`	3rem (48px)
`spacing-16`	`p-16` / `m-16`	4rem (64px)
`spacing-18`	`p-18` / `m-18`	4.5rem
`spacing-22`	`p-22` / `m-22`	5.5rem
`spacing-72`	`p-72` / `m-72`	18rem
`spacing-80`	`p-80` / `m-80`	20rem

Border Radius

Token	Tailwind Class	Value
`radius-none`	`rounded-none`	0
`radius-sm`	`rounded-sm`	0.25rem (4px)
`radius-md`	`rounded-md`	0.375rem (6px)
`radius-lg`	`rounded-lg`	0.5rem (8px)
`radius-xl`	`rounded-xl`	0.75rem (12px)
`radius-2xl`	`rounded-2xl`	1rem (16px)
`radius-full`	`rounded-full`	9999px

Shadows

Token	Tailwind Class	Usage
`shadow-sm`	`shadow-sm`	Subtle elevation
`shadow-md`	`shadow-md`	Cards, dropdowns
`shadow-lg`	`shadow-lg`	Modals, popovers
`shadow-overlay`	`shadow-overlay`	Full-screen overlays

Motion

Durations

Token	Tailwind Class	Value
`duration-instant`	`duration-instant`	0ms
`duration-fast`	`duration-fast`	100ms
`duration-normal`	`duration-normal`	200ms
`duration-slow`	`duration-slow`	350ms
`duration-xslow`	`duration-xslow`	500ms

Easing

Token	Tailwind Class	Value
`ease-default`	`ease-default`	cubic-bezier(0.4, 0, 0.2, 1)
`ease-in`	`ease-in`	cubic-bezier(0.4, 0, 1, 1)
`ease-out`	`ease-out`	cubic-bezier(0, 0, 0.2, 1)
`ease-spring`	`ease-spring`	cubic-bezier(0.34, 1.56, 0.64, 1)

Z-Index Scale

Token	Tailwind Class	Value	Usage
`z-dropdown`	`z-dropdown`	1000	Dropdowns, menus
`z-sticky`	`z-sticky`	1100	Sticky elements
`z-overlay-window`	`z-overlay-window`	1200	Electron overlays
`z-modal`	`z-modal`	1300	Modals
`z-toast`	`z-toast`	1400	Toast notifications

Glassmorphic / Call Overlay Tokens

Specialized tokens for the desktop overlay UI:

Token	Usage
`glass-bg`	Overlay background (#0f1510)
`glass-text`	Overlay text (#e5eae5)
`glass-subtle`	Hover states, cards
`glass-card`	Transcript cards, responses
`glass-divider`	Dividers
`glass-hover`	Button hover states
`glass-border`	All borders
`glass-pressed`	Button active/pressed
`glass-panel-*`	Panel backgrounds (25%, 40%, 95% alpha)
`glass-danger`	Risk panel background
`glass-warning`	Objections panel background
`glass-success`	Payment panel background

Dark Mode

Dark mode is activated by adding .dark class to <html>:

import { ThemeProvider } from '@cosella/tokens';

<ThemeProvider>{children}</ThemeProvider>

All tokens automatically adapt to dark mode via CSS custom properties.

Component Classes

The components.css file provides pre-built CSS classes:

/* Layout */
.cs-page-shell     /* Page container */
.cs-page-stack     /* Vertical stack */
.cs-page-header    /* Page header */

/* Panels */
.cs-panel          /* Card/panel */

/* Forms */
.cs-input          /* Text input */
.cs-select         /* Select dropdown */

/* Navigation */
.cs-tabs           /* Tab container */
.cs-tab            /* Tab item */
.cs-tab-active     /* Active tab */

/* Tables */
.cs-table-wrap     /* Table wrapper */
.cs-table          /* Table element */
.cs-table-head     /* Table header */
.cs-table-row      /* Table row */
.cs-table-cell     /* Table cell */

/* Badges */
.cs-badge          /* Base badge */
.cs-badge-blue     /* Blue badge */
.cs-badge-green    /* Green badge */
.cs-badge-red      /* Red badge */
.cs-badge-amber    /* Amber badge */
.cs-badge-purple   /* Purple badge */

/* Buttons */
.cs-btn            /* Base button */
.cs-btn-primary    /* Primary button */
.cs-btn-outline    /* Outline button */
.cs-btn-ghost      /* Ghost button */
.cs-btn-destructive /* Destructive button */
.cs-btn-sm         /* Small button */
.cs-btn-md         /* Medium button */
.cs-btn-lg         /* Large button */

/* Typography */
.cs-page-title     /* Page title */
.cs-section-title  /* Section title */
.cs-card-title     /* Card title */
.cs-body           /* Body text */
.cs-label          /* Form label */

Next Steps

UI Components - Component library
Vibecoder UI Guide - How to use tokens in UI changes
Contributing - Add new tokens