Design Tokens

The @repo/design-tokens package is a leaf-layer package that contains no TypeScript -- only tokens.css (CSS custom properties) and SVG logo assets. It is imported by globals.css in @repo/web and provides every color, shadow, radius, and font fallback used across the application.

Package Exports

Import path	Contents
@repo/design-tokens/tokens.css	All CSS custom properties (colors, shadows, radii)
@repo/design-tokens/logo/trovella-icon.svg	Diamond icon for light backgrounds
@repo/design-tokens/logo/trovella-icon-dark.svg	Diamond icon for dark/teal backgrounds
@repo/design-tokens/logo/trovella-favicon.svg	Simplified 16px favicon variant

Color System

All colors are stored as bare HSL triplets (H S% L%) and wrapped with hsl() at the point of use. This format allows Tailwind's opacity modifier syntax (bg-primary/20) to work correctly.

Brand Palette

The brand identity follows the Creator + Magician + Explorer archetype with three core color families:

Role	Token	Light Mode HSL	Visual Description
Primary	--primary	188 32% 33%	Deep teal -- CTAs, links, active states
Secondary	--secondary	188 35% 92%	Light teal wash -- subtle highlights
Accent	--accent	45 55% 52%	Gold/brass -- discovery moments, sparingly

The accent color is reserved for "discovery moments" -- feature card icon backgrounds, achievement indicators, and the sidebar accent. It should not be used for primary actions or large surface areas.

Surface Colors

Token	Light Mode	Dark Mode	Usage
--background	40 20% 97%	40 10% 8%	Page background (warm off-white / near-black)
--foreground	40 10% 10%	40 10% 95%	Primary text
--card	0 0% 100%	40 8% 11%	Card surfaces
--card-foreground	40 10% 10%	40 10% 95%	Card text
--popover	0 0% 100%	40 8% 11%	Dropdown/popover surfaces
--muted	40 12% 95%	40 8% 14%	De-emphasized backgrounds
--muted-foreground	40 8% 45%	40 8% 55%	De-emphasized text

State Colors

Four semantic state colors, each with a full set: base, foreground, muted background, and muted foreground:

State	Base Token	Light HSL	Usage
Success	--success	155 40% 40%	Green -- completion, positive feedback
Warning	--warning	45 60% 50%	Amber -- caution, degraded states
Error	--error	5 65% 48%	Red -- failures, validation errors
Info	--info	220 50% 50%	Blue -- informational notices
Destructive	--destructive	5 65% 48%	Red -- delete actions, same hue as error

Each state token has -foreground, -muted, and -muted-foreground variants. For example, --success-muted provides a pale green background for success banners, and --success-muted-foreground provides readable text on that background.

Sidebar Colors

The sidebar uses a dark teal background (188 30% 25% in light mode), creating a persistent brand-colored navigation rail regardless of the active theme:

Token	Light Mode	Dark Mode
--sidebar	188 30% 25%	188 30% 10%
--sidebar-foreground	0 0% 100%	40 10% 95%
--sidebar-accent	45 50% 60%	45 50% 55%
--sidebar-border	188 30% 20%	188 20% 15%

Border and Input Colors

Token	Light Mode	Dark Mode	Usage
--border	40 10% 88%	40 8% 18%	Default borders
--input	40 10% 82%	40 8% 22%	Input field borders
--ring	188 35% 50%	188 30% 40%	Focus rings (teal-tinted)

Chart Palette

Five chart colors for data visualizations, cycling through the brand palette:

Token	Light Mode	Description
--chart-1	188 30% 40%	Teal (primary family)
--chart-2	45 55% 52%	Gold (accent family)
--chart-3	155 30% 40%	Green (success family)
--chart-4	30 45% 45%	Warm brown
--chart-5	10 40% 45%	Muted red

Typography

Three font families, loaded by Next.js in layout.tsx and mapped to Tailwind utilities in globals.css:

Role	Font	CSS Variable	Tailwind Class	Weights	Usage
Body	DM Sans	--font-body	font-sans	400, 500, 600, 700	Body text, UI labels, navigation
Display	DM Serif Display	--font-display	font-serif	400 only	Headings (h1-h6), card titles
Mono	JetBrains Mono	--font-mono	font-mono	400-700	Code blocks, data tables

Typography Rules

• DM Serif Display has only weight 400. Faux bold renders poorly -- use size and color for heading hierarchy, never font-weight.
• Headings in globals.css get font-serif font-bold tracking-tight applied via the base layer. The font-bold declaration is safe because DM Sans serves as the fallback in the serif stack, and the browser applies bold correctly from the loaded serif font's single weight.
• Body text uses font-sans (the Tailwind default, mapped to --font-body).
• Metadata and labels: font-sans text-sm text-muted-foreground.

Shadows

All shadows are teal-tinted (hue 188, saturation 20%, lightness 30%) for brand consistency. The opacity ranges from 5% (--shadow-2xs) to 15% (--shadow-2xl):

Token	Usage
--shadow-2xs	Subtle lift for small elements
--shadow-xs, --shadow-sm	Default cards
--shadow, --shadow-md	Elevated cards, hover states
--shadow-lg, --shadow-xl	Dialogs, modals
--shadow-2xl	Large floating panels

Border Radius

A hierarchical scale computed from a single --radius base value (0.5rem):

Token	Value	Usage
--radius-sm	calc(0.5rem - 4px)	Small elements (badges, chips)
--radius-md	calc(0.5rem - 2px)	Cards, dropdowns
--radius-lg	0.5rem	Modals, dialogs
--radius-xl	calc(0.5rem + 4px)	Large containers, hero sections
rounded-full	(Tailwind utility)	Pills, avatars, circular elements

Changing the --radius base value adjusts the entire scale proportionally.

Icon Rules (Lucide)

All icons use Lucide with a 2px default stroke width:

Size	Pixels	Usage
Inline	16px (size-4)	Next to text, within buttons
Navigation	20px (size-5)	Sidebar nav items, top bar actions
Cards	24px (size-6)	Feature card icons, empty states
Large	32px (size-8)	Empty state illustrations

Icon color conventions:

• text-primary for active/interactive icons
• text-muted-foreground for inactive/decorative icons
• text-destructive for delete/danger actions
• Feature card icons: place on a bg-{color}/10 tinted background (e.g., bg-primary/10 text-primary or bg-accent/10 text-accent)

Logo Assets

The design tokens package exports three SVG logo variants:

File	Usage	Notes
trovella-icon.svg	Light backgrounds	Full-color diamond with gradient opacity facets
trovella-icon-dark.svg	Dark or teal backgrounds	Adjusted for contrast
trovella-favicon.svg	Browser favicon (16px)	Simplified geometry

Minimum clearspace: half the icon width on all sides.

The TrovellaLogo React component (src/components/brand/trovella-logo.tsx) renders the diamond icon inline with an optional "trovella" wordmark in DM Serif Display. Available in sm, md, and lg sizes.

Usage Rules for AI Agents

The token file includes an inline usage guide (CSS comment block) designed for AI agent consumption. Key rules:

1. Always use semantic tokens -- bg-primary, text-foreground, border-border
2. Never use Tailwind default colors -- no bg-indigo-*, bg-blue-*, bg-violet-*
3. Never use bare hex or oklch values in component code
4. Headings: font-serif (mapped to DM Serif Display), use size for hierarchy, not weight
5. Body text: font-sans (mapped to DM Sans)
6. Code/data: font-mono (mapped to JetBrains Mono)