Stagewise UI theming, design tokens, derived utilities, and component library reference. Use when creating, editing, or reviewing UI in apps/browser, implementing new screens or components, or styling with Tailwind in the stagewise codebase.
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.
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';
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.
Defined in theme.css, tokens auto-switch between light and dark mode via prefers-color-scheme.
| Tailwind class | Token | Usage |
|---|---|---|
bg-app-background | --color-app-background | Outermost app chrome |
bg-background | --color-background | Main content areas, cards, panels |
bg-surface-1 | --color-surface-1 | First elevation above background |
bg-surface-2 | --color-surface-2 | Second elevation (nested elements) |
bg-surface-3 | --color-surface-3 | Third elevation (deeply nested) |
bg-surface-tinted | --color-surface-tinted | Primary-tinted highlight surface |
bg-overlay | --color-overlay | Modal/dialog backdrops (use with opacity) |
| Tailwind class | Usage |
|---|---|
text-foreground | Primary readable text |
text-muted-foreground | Secondary/less important text |
text-subtle-foreground | Hints, placeholders, disabled text |
text-primary-foreground | Accent text (links, highlights) |
text-solid-foreground | Text on solid/primary backgrounds |
| Tailwind class | Usage |
|---|---|
border-border | Regular borders |
border-border-subtle | Subtle/lighter borders |
| Tailwind class | Usage |
|---|---|
bg-primary-solid | Solid primary fill (buttons, badges) |
Pattern: (bg|text)-{success|error|warning|info}-{background|foreground|solid}
Light mode: Use bg-background for cards. Depth comes from shadows.
Dark mode: Use escalating surfaces based on nesting depth:
bg-background → use bg-surface-1bg-surface-1 → use bg-surface-2bg-surface-2 → use bg-surface-3Shadow utilities (defined in shadows.css):
shadow-elevation-1 — subtle card shadowshadow-elevation-2 — prominent popup/modal shadowThese auto-derive border/hover/active colors from an element's background. Requires the element to have a bg-* class set.
border-derived-subtle — light borderborder-derived — regular borderborder-derived-strong — strong borderborder-derived-lighter-subtle / border-derived-lighter — explicitly lighterSame pattern for rings: ring-derived-subtle, ring-derived, ring-derived-strong
hover:bg-hover-derived — hover backgroundactive:bg-active-derived — active/pressed backgroundhover:text-hover-derived — hover textactive:text-active-derived — active textbg-derived-lighter / bg-derived-lighter-subtlebg-derived-darker / bg-derived-darker-subtletext-derived-lighter / text-derived-lighter-subtleDefined in animations.css. Use as Tailwind classes:
| Class | Effect |
|---|---|
animate-progress-bar-indicator | Repeating slide for progress bars |
animate-skeleton-shimmer | Loading shimmer for skeletons |
animate-caret-blink | Blinking caret for inputs |
animate-icon-pulse | Stroke-width pulse for icons |
animate-pulse-full | Full opacity pulse (0→1→0) |
animate-text-pulse | Muted↔foreground text pulse |
animate-text-pulse-warning | Foreground↔warning text pulse |
shimmer-text | Shimmering gradient text effect |
shimmer-text-primary | Primary-colored shimmer preset |
shimmer-text-once | One-shot shimmer that settles |
Shimmer config: shimmer-duration-{ms}, shimmer-from-{color}, shimmer-to-{color}
All components follow these patterns:
@base-ui/react) — unstyled React primitivesclass-variance-authority) — variant and size propscn() — all accept className for overridesDialog + DialogContent + DialogTitleimport { 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>
For detailed API and props of each component, see components-reference.md.
| Component | Import path | Key props |
|---|---|---|
| Button | components/button | variant: primary, secondary, destructive, warning, success, ghost. size: xs, sm, md, lg, icon-2xs, icon-xs, icon-sm, icon-md |
| Input | components/input | size: xs, sm, md. debounce: ms. Built on Base UI Input |
| Select | components/select | items, value, onValueChange, size, triggerVariant: ghost/secondary, multiple |
| Checkbox | components/checkbox | size: xs, sm, md. Built on Base UI Checkbox |
| Switch | components/switch | size: xs, sm, md. Built on Base UI Switch |
| Radio | components/radio | RadioGroup + Radio + RadioLabel. Built on Base UI Radio |
| Tabs | components/tabs | Tabs, TabsList, TabsTrigger, TabsContent |
| Dialog | components/dialog | Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogClose, DialogHeader, DialogFooter |
| Popover | components/popover | Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription, PopoverClose, PopoverFooter |
| Tooltip | components/tooltip | Tooltip, TooltipTrigger, TooltipContent, TooltipProvider |
| Menu | components/menu | Menu, MenuTrigger, MenuContent, MenuItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuSubmenuContent |
| Collapsible | components/collapsible | Collapsible, CollapsibleTrigger (size: default/condensed), CollapsibleContent |
| Progress | components/progress | Progress, ProgressTrack (variant: normal/warning, busy, slim), ProgressLabel, ProgressValue |
| Skeleton | components/skeleton | variant: rectangle, circle, text. size: xs–full. animate: boolean |
| Form | components/form | Form, FormFieldset, FormField, FormFieldLabel, FormFieldTitle, FormFieldDescription, FormFieldError, FormFieldSeparator |
| Resizable | components/resizable | ResizablePanelGroup, ResizablePanel, ResizableHandle. Built on react-resizable-panels |
| OverlayScrollbar | components/overlay-scrollbar | Custom scrollbar wrapper |
| Toaster | components/toaster | Toast notification system |
| Breadcrumb | components/breadcrumb | Breadcrumb navigation |
| Combobox | components/combobox | Combobox/autocomplete input |
| InputOtp | components/input-otp | OTP code input |
| SearchableSelect | components/searchable-select | Searchable dropdown select |
| SplitText | components/split-text | Text splitting utility |
| PreviewCard | components/preview-card | Card with preview content |
| LogoText | components/logo-text | Stagewise logo text |
Picking a background:
bg-app-backgroundbg-backgroundbg-surface-1 → bg-surface-2 → bg-surface-3Picking text color:
text-foregroundtext-muted-foregroundtext-subtle-foregroundtext-primary-foregroundBorders & states (on elements with bg-*):
border border-derived or border border-derived-subtlehover:bg-hover-derivedactive:bg-active-derivedIcons: Use lucide-react or nucleo-ui-fill-18 (project-specific icon set).
Preview components and color definitions:
pnpm --filter stagewise storybook