Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.deep.space/llms.txt

Use this file to discover all available pages before exploring further.

DeepSpace ships 15 ready-made theme presets and CSS-variable-based theming. Most apps pick a preset with <html data-theme="..."> and never touch the runtime API. The exports below are for advanced cases - applying themes dynamically, embedding DeepSpace surfaces in a deployed site, or building a theme picker. 
import {
  DeepSpaceThemeProvider,
  useIsDarkTheme, isDarkColor,
  applyDeepSpaceTheme, clearDeepSpaceTheme, readThemeFromDOM,
  applyUIThemeTokens,
  DEEPSPACE_THEME_PROPERTIES,
  DEFAULT_USER_COLORS, getUserColor,
} from 'deepspace'

​
<DeepSpaceThemeProvider theme={...}>

Wraps the tree with theme tokens. Reads from --color-* CSS variables by default - usually you don’t need this; the [data-theme] attribute on <html> does the work. Reach for it when:
  • Embedding DeepSpace surfaces (cross-app pills, directory panels) on a deployed site
  • Switching themes at runtime from React state
  • Building a theme picker UI

​
Hooks and utilities

ExportSignatureDescription
useIsDarkTheme()() => booleanTrue if the current theme is a dark variant.
isDarkColor(color)(color: string) => booleanLuminance check on a single color value.

​
Imperative API

type DeepSpaceThemeConfig = {
  primaryColor: string
  panelColor?: string
  secondaryColor: string
  accentColor: string
  accentContrastColor?: string         // default '#ffffff'
  textColor: string
  shadowColor?: string                 // default '#000000'
  borderColor?: string                 // defaults to secondaryColor
  backgroundColor?: string             // defaults to primaryColor
  highlightColor?: string              // default '#ffffff'
  glassmorphism?: boolean              // default true
}

applyDeepSpaceTheme(config: DeepSpaceThemeConfig, root?: HTMLElement): void
clearDeepSpaceTheme(root?: HTMLElement): void
readThemeFromDOM(root?: HTMLElement): DeepSpaceThemeConfig
applyUIThemeTokens(
  theme: 'light' | 'dark',
  root?: HTMLElement,
  accent?: { color: string; hover: string; secondary: string },
): void
FunctionPurpose
applyDeepSpaceThemeSets the --theme-* CSS variables consumed by cross-app surfaces.
clearDeepSpaceThemeRemoves theme variables.
readThemeFromDOMInspects --color-* tokens and derives a theme config.
applyUIThemeTokensSets the static --ui-* tokens (surfaces, text, borders) for the chosen mode. The optional accent overrides the accent/hover/secondary triplet - if omitted, the current --theme-accent / --theme-secondary are read from computed styles.
DEEPSPACE_THEME_PROPERTIES is the readonly tuple of CSS custom properties the theme defines - useful for introspection or building custom clear logic.

​
User colors

// 12-color palette for cursors, avatars, and "who's typing" pills
const DEFAULT_USER_COLORS: readonly string[]

// Deterministic hash: same userId always returns the same color
function getUserColor(userId: string, palette?: string[]): string

import { getUserColor } from 'deepspace'

<div style={{ color: getUserColor(peer.userId) }}>{peer.userName}</div>
Pass a custom palette to match your brand: 
const color = getUserColor(userId, ['#1D4ED8', '#16A34A', '#DC2626'])

​
UI primitives (SDK-provided)

The SDK ships a small set of UI primitives, but the scaffolded app usually includes its own copies in src/components/ui/. Check _app.tsx to see which ToastProvider is wrapped in the tree before importing useToast.
Mixing SDK and local contexts produces useToast must be used within ToastProvider. The scaffold’s local src/components/ui/ ships its own React contexts; the SDK’s hooks only find providers from the same module instance. Import primitives from ../components/ui (local), not from deepspace, unless _app.tsx is wrapped in the SDK’s ToastProvider.
ExportDescription
ToastProviderContext for toasts (SDK version)
useToast()Returns { success, error, warning, info, toast, dismiss, dismissAll }

​
Theme presets reference

The scaffold’s 15 presets are defined in src/themes.css with a typed catalog in src/themes.ts. Pick by setting <html data-theme="...">: Dark themes: slate (default), ink, aurora, midnight, forest, ember, graphite, noir Light themes: linen, mist, sand, bloom, paper, lavender, citrus For customization (overriding tokens, adding new presets, light/dark toggles), see the scaffold’s themes.ts header comments.

​
See also