Stage UI Design System

Stage UI Design System

All UI in apps/browser/ is built on @stagewise/stage-ui — a shared design system using OKLCH colors, Tailwind CSS 4, and Base UI (React) primitives.

Importing Styles & Components

Styles — import the CSS entry point (already done in the browser app):

@import "../../../../../packages/stage-ui/src/styles/index.css";

Components — import via package alias:

import { Button } from '@stagewise/stage-ui/components/button';
import { Tooltip, TooltipTrigger, TooltipContent } from '@stagewise/stage-ui/components/tooltip';

Utility function — cn() merges Tailwind classes (clsx + twMerge):

import { cn } from '@stagewise/stage-ui/lib/utils';

Color System (OKLCH)

All colors use OKLCH with a shared hue --H: 265 (purple). The palette is defined in palette.css.

Base colors (--color-base-50 to --color-base-950): Low-chroma, nearly grayscale but subtly tinted. Used for 95%+ of the app.

Primary colors (--color-primary-50 to --color-primary-950): High-chroma, saturated. Used for CTAs, links, active states.

Semantic colors: success (green), error (red), warning (yellow), info (blue) — each has -background, -foreground, -solid variants that auto-switch with light/dark.

Theme Tokens

Defined in theme.css, tokens auto-switch between light and dark mode via prefers-color-scheme.

Backgrounds

Text

Borders

Primary

Semantic

Pattern: (bg|text)-{success|error|warning|info}-{background|foreground|solid}

Elevation & Shadows

Light mode: Use bg-background for cards. Depth comes from shadows. Dark mode: Use escalating surfaces based on nesting depth:

• Element on bg-background → use bg-surface-1
• Element on bg-surface-1 → use bg-surface-2
• Element on bg-surface-2 → use bg-surface-3

Shadow utilities (defined in shadows.css):

• shadow-elevation-1 — subtle card shadow
• shadow-elevation-2 — prominent popup/modal shadow

Derived Utilities

These auto-derive border/hover/active colors from an element's background. Requires the element to have a bg-* class set.

Borders (derived from background)

• border-derived-subtle — light border
• border-derived — regular border
• border-derived-strong — strong border
• border-derived-lighter-subtle / border-derived-lighter — explicitly lighter

Same pattern for rings: ring-derived-subtle, ring-derived, ring-derived-strong

Hover & Active States

• hover:bg-hover-derived — hover background
• active:bg-active-derived — active/pressed background
• hover:text-hover-derived — hover text
• active:text-active-derived — active text

Explicit Lighten/Darken (ignores dark/light mode)

• bg-derived-lighter / bg-derived-lighter-subtle
• bg-derived-darker / bg-derived-darker-subtle
• text-derived-lighter / text-derived-lighter-subtle

Animations

Defined in animations.css. Use as Tailwind classes:

Shimmer config: shimmer-duration-{ms}, shimmer-from-{color}, shimmer-to-{color}

Component Patterns

All components follow these patterns:

1. Built on Base UI (@base-ui/react) — unstyled React primitives
2. Variants via CVA (class-variance-authority) — variant and size props
3. Class merging via cn() — all accept className for overrides
4. Compound components — e.g. Dialog + DialogContent + DialogTitle

Typical usage example

import { Button } from '@stagewise/stage-ui/components/button';
import { Tooltip, TooltipTrigger, TooltipContent } from '@stagewise/stage-ui/components/tooltip';

<Tooltip>
  <TooltipTrigger>
    <Button variant="secondary" size="sm">Click me</Button>
  </TooltipTrigger>
  <TooltipContent side="top">Helpful hint</TooltipContent>
</Tooltip>

Available Components

For detailed API and props of each component, see components-reference.md.

Quick Decision Guide

Picking a background:

• Top-level page → bg-app-background
• Card/panel → bg-background
• Nested element → escalate: bg-surface-1 → bg-surface-2 → bg-surface-3

Picking text color:

• Primary content → text-foreground
• Secondary info → text-muted-foreground
• Placeholder/disabled → text-subtle-foreground
• Links/accents → text-primary-foreground

Borders & states (on elements with bg-*):

• Border: border border-derived or border border-derived-subtle
• Hover: hover:bg-hover-derived
• Active: active:bg-active-derived

Icons: Use lucide-react or nucleo-ui-fill-18 (project-specific icon set).

Storybook

Preview components and color definitions:

pnpm --filter stagewise storybook