Theming

CSS variables

The theme in @cloudvoyant/helical-ui matches shadcn/ui’s theming exactly: semantic tokens such as --background, --foreground, --primary, and --secondary are defined under :root for light mode and overridden under .dark. On top of the shadcn token set, helical-ui adds --success, --danger, --warn, and --info (each with a -foreground) for semantic status colors used by Button and Badge, plus the standard font stacks — marked as helical-ui additions in theme.css.

/* libs/helical-ui/src/theme.css
   Base shadcn-style theme. The token set below matches shadcn/ui's standard
   "Neutral" theme (see https://ui.shadcn.com/docs/theming) — light + dark.
   helical-ui additions (status colors + font stacks) are marked inline. */

@custom-variant dark (&:is(.dark *));

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  /* helical-ui addition — semantic status colors (used by Button/Badge). */
  --color-success: var(--success);
  --color-success-foreground: var(--success-foreground);
  --color-danger: var(--danger);
  --color-danger-foreground: var(--danger-foreground);
  --color-warn: var(--warn);
  --color-warn-foreground: var(--warn-foreground);
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
  /* end helical-ui addition */
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-ring: var(--sidebar-ring);
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --radius-4xl: calc(var(--radius) * 2.6);
}

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  /* helical-ui addition — semantic status colors (used by Button/Badge). */
  --success: oklch(0.72 0.19 149);
  --success-foreground: oklch(0.985 0 0);
  --danger: oklch(0.577 0.245 27.325);
  --danger-foreground: oklch(0.985 0 0);
  --warn: oklch(0.65 0.17 70);
  --warn-foreground: oklch(0.2 0.04 95);
  --info: oklch(0.55 0.22 256);
  --info-foreground: oklch(0.985 0 0);
  /* end helical-ui addition */
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --chart-1: oklch(0.646 0.222 41.116);
  --chart-2: oklch(0.6 0.118 184.704);
  --chart-3: oklch(0.398 0.07 227.392);
  --chart-4: oklch(0.828 0.189 84.429);
  --chart-5: oklch(0.769 0.188 70.08);
  --sidebar: oklch(0.985 0 0);
  --sidebar-foreground: oklch(0.145 0 0);
  --sidebar-primary: oklch(0.205 0 0);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.97 0 0);
  --sidebar-accent-foreground: oklch(0.205 0 0);
  --sidebar-border: oklch(0.922 0 0);
  --sidebar-ring: oklch(0.708 0 0);
  /* helical-ui addition — font stacks (standard shadcn globals; themes may override). */
  --font-sans:
    ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
  --font-serif: ui-serif, Georgia, Cambria, 'Times New Roman', Times, serif;
  --font-heading: var(--font-sans);
  /* end helical-ui addition */
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  /* helical-ui addition — semantic status colors (used by Button/Badge). */
  --success: oklch(0.6 0.17 149);
  --success-foreground: oklch(0.12 0.02 149);
  --danger: oklch(0.704 0.191 22.216);
  --danger-foreground: oklch(0.985 0 0);
  --warn: oklch(0.72 0.15 70);
  --warn-foreground: oklch(0.15 0.03 95);
  --info: oklch(0.62 0.22 256);
  --info-foreground: oklch(0.12 0.03 256);
  /* end helical-ui addition */
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.556 0 0);
  --chart-1: oklch(0.488 0.243 264.376);
  --chart-2: oklch(0.696 0.17 162.48);
  --chart-3: oklch(0.769 0.188 70.08);
  --chart-4: oklch(0.627 0.265 303.9);
  --chart-5: oklch(0.645 0.246 16.439);
  --sidebar: oklch(0.205 0 0);
  --sidebar-foreground: oklch(0.985 0 0);
  --sidebar-primary: oklch(0.488 0.243 264.376);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.269 0 0);
  --sidebar-accent-foreground: oklch(0.985 0 0);
  --sidebar-border: oklch(1 0 0 / 10%);
  --sidebar-ring: oklch(0.556 0 0);
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
  /* helical-ui page scrollbar. `Page` relies on the document scrollbar (sticky
     gutters + footer bottom-out need window scrolling, so the page body is
     never wrapped in Ark ScrollArea). Style that document scrollbar — and any
     other native scrollbar — to match the Scroll component's look: thin,
     rounded, --border-based. The Scroll component's own viewport keeps hiding
     its native scrollbar ([scrollbar-width:none] / ::-webkit-scrollbar:hidden),
     so this never double-styles it. */
  * {
    scrollbar-width: thin;
    scrollbar-color: color-mix(in oklab, var(--border) 40%, transparent) transparent;
  }
  ::-webkit-scrollbar {
    width: 0.5rem;
    height: 0.5rem;
  }
  ::-webkit-scrollbar-track {
    background: transparent;
  }
  ::-webkit-scrollbar-thumb {
    background-color: color-mix(in oklab, var(--border) 40%, transparent);
    border-radius: 9999px;
    border: 2px solid transparent;
    background-clip: padding-box;
  }
  ::-webkit-scrollbar-thumb:hover {
    background-color: var(--border);
  }
}

Theme presets

Beyond the base shadcn “Neutral” palette, @cloudvoyant/helical-ui ships over fifty shadcn-compatible theme presets in @cloudvoyant/helical-ui/themes.css. Each preset is a .theme-{name} block for light mode and a .theme-{name}.dark block for dark mode that overrides the same CSS variables:

@import 'tailwindcss';
@import '@cloudvoyant/helical-ui/theme.css';
@import '@cloudvoyant/helical-ui/themes.css';

Apply a preset by adding its class to <html> — e.g. class="theme-catppuccin". Any token a preset doesn’t override (for example a helical-ui status color) falls back to the base :root / .dark values. The docs site’s theme selector demonstrates the full list.

Dark mode

Set the dark class on <html> for dark mode, and use a theme-{name} class to pick a preset. The docs site persists both — a vortex:color-mode preference (light / dark / system) and a vortex:theme preset — and honors prefers-color-scheme by default.